Skip to content

Latest commit

 

History

History
executable file
·
171 lines (127 loc) · 5.83 KB

03_configuration.rst

File metadata and controls

executable file
·
171 lines (127 loc) · 5.83 KB

Right Configuration

Generate Missing SSH Keys

The following command will generate missing ssh keys for a user:

if [ ! -f ~/.ssh/id_rsa ]; then ssh-keygen -N '' -f ~/.ssh/id_rsa; fi

Configure git

Publishing on the web is a form of coding, and code belongs in a repository. While there are many options for repositories, git [1] has become a de facto standard for publicly exchanged projects. Enter the following console commands to configure git:

git config --global user.name "firstname lastname"
git config --global user.email "email@domain"
git config --global branch.master.remote origin
git config --global branch.master.merge refs/heads/master
git config --global --add color.ui true

These global settings are recorded in home directory file :file:`~/.gitconfig`.

Create a Project Folder

Documentation is treated as a project. Work is divided into projects which are stored locally as sub-folders of a :file:`Projects` folder. Oddly, Linux desktops create folders for music, downloads, pictures, videos, and so forth, but a place to do actual work? Missing. Create the missing folder and start your first project with the following command:

git init ~/Projects/doc-firsttask

This creates the directory :file:`~/Projects/doc-firsttask/.git` where repository information is kept for that project.

Prepare .gitignore

Your project will contain files with content that you create, and other files which are generated by the system. The git repository should track content and not system files. Using nano or kate, create a :file:`.gitignore` file to identify untracked files to git. [2] Here is some suggested content for :file:`.gitignore`:

# ignore editor backup files
*~
*/*~
# ignore compilation from make
*build/*
*/*build/*
# ignore deployment content
*deploy/*
*/*deploy/*
# keep hidden placeholder files which preserve directories
!.gitkeep
!*/.gitkeep

Add Sphinx to a Project

Add the Sphinx documentation features to your new project from the console as follows:

cd ~/Projects/doc-firsttask
sphinx-quickstart

Answer the resulting questions, which are:

Root path for the documentation [.]:
Separate source and build directories (y/N) [n]:
Name prefix for templates and static dir [_]:
Project name: __First Project__
Author name(s): __Your Name Here__
Project version: __1.0__
Project release [1.0]:
Source file suffix [.rst]:
Name of your master document (without suffix) [index]:
Do you want to use the epub builder (y/N) [n]:
autodoc: automatically insert docstringss from modules (y/N) [n]:
doctest: automatically test code snippets in doctest blocks (y/N) [n]:
intersphinx link between Sphinxx documentation of different projects (y/N) [n]:
todo: write "todo" entries that can be shown or hidden on build (y/N) [n]:
coverage: checks for documentation coverage (y/N) [n]:
pngmath: include math, rendered as PNG images (y/N) [n]:
mathjax: include math, rendered in the browser by MathJax (y/N) [n]:
ifconfig: conditional inclusion of content based on config values (y/N) [n]:
viewcode: include links to the source code of documented Python objects (y/N) [n]:
Create Makefile? (Y/n) [y]:
Create Windows command file? (Y/n) [y]: __n__

Only four questions actually require answering; the rest are defaulted.

Add Documentation Folders

A publication may require additional folders to hold images, downloads, static content, web program includes, and deployed results. Following are commands to create these folders:

cd ~/Projects/doc-firsttask
mkdir _build;     touch _build/.git_keep
mkdir _deploy;    touch _deploy/.git_kep
mkdir _downloads; touch _downloads/.git_keep
mkdir _images;    touch _images/.git_keep
mkdir _include;   touch _include/.git_keep
mkdir _static;    touch _static/.git_keep

You can avoid typing all these commands, however, by downloading the following two scripts to your :file:`~/Projects` folder:

To start a new documentation project, from :file:`~/Projects`, run the command:

bash docproject-start.sh {document_foldername}

To add a documentation branch to a code project repository, from :file:`~/Projects`, run the command:

bash docbranch-add.sh {project_foldername}

Note

These scripts assume that you have already created the documentation or project folder, that git init has been run on the folder, and that a remote host repository is named using git remote add origin {remotename}.

Add Changes to git

Now add your changes to git [3] and view the results with the commands:

git add .
git status
git commit -m "Empty project directory for firsttask"

Summary Configuration

This section covered:

  • Generating Missing SSH keys
  • Configuring git
  • Creating a Projects folder and the first project within it
  • Initializing the project for git tracking
  • Applying Sphinx documentation tools on the project
  • Adding other folders for later use
  • Performing the first git commit

Footnotes

[1]For information on git, see http://en.wikipedia.org/wiki/Git_(software). A git online reference manual is at http://gitref.org/.
[2]GitHub Help has an excellent explanation of :file:`.gitignore`.
[3]Try GitHub offers a quick tutorial on Git and GitHub to bring you up to speed.