.. _configure:

#############################
 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** [#]_ 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. 

.. _gitignore:

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. [#]_ 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:

+ :download:`Documentation project startup script <_downloads/docproject-start.sh>` 
+ :download:`Add documentation to project script <_downloads/docbranch-add.sh>` 

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 [#]_ 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

------

.. rubric:: Footnotes

.. [#] For information on git, see http://en.wikipedia.org/wiki/Git_(software). 
       A git online reference manual is at http://gitref.org/.

.. [#] `GitHub Help <http://help.github.com/ignore-files/>`_ has an excellent 
       explanation of :file:`.gitignore`.

.. [#] `Try GitHub <http://try.github.com/>`_ offers a quick tutorial on Git 
       and GitHub to bring you up to speed.