rattail-tutorial/docs/start-docs.rst

.. highlight:: sh

Documenting Your Project
========================

At this point we assume you already have created a new project, and established
the Git repo for it etc.

Now we'll walk through the steps for creating documentation for your project.
We won't get too far in the weeds here but will seek to establish a foundation
to which you can easily add later.

The reason we cover docs so early in the game, is because as this tutorial
project itself is being built, the docs in practice will come before most of
the app code.  So we are just documenting steps as we encounter them, while
building the tutorial.

Install Sphinx
--------------

As is typical for Python projects, the docs we maintain within our project will
use `Sphinx`_, which in turn uses `reStructuredText`_ for the primary syntax.
Sphinx offers a lot of convenience, and is configurable, can be extended etc.

.. _Sphinx: https://www.sphinx-doc.org/
.. _reStructuredText: https://docutils.readthedocs.io/en/sphinx-docs/user/rst/quickstart.html

You may not yet have Sphinx installed to your virtualenv, but we can fix that
now.  Run this command just to be sure::

   pip install rattail[docs]

Sphinx Quickstart
-----------------

Sphinx comes with a "quickstart" command, which you can use to walk through the
process of creating a new documentation folder.

First change directory to your project's source repo folder, then run the
quickstart command like so.  Note, this will create a 'docs' folder::

   cd ~/src/rattail-tutorial
   sphinx-quickstart --project rattail-tutorial docs
    
You will be prompted for a few things, mostly you can use the default option or
provide some basic answer to each, and it will work out okay.

Before you go any further you may want to consider committing the generated
docs code as-is, to help keep track of changes *you* make from there::

   git add docs
   git commit -m "Initial docs as generated by sphinx-quickstart"

Building the Docs
-----------------

With the above steps complete, you should have a basic docs folder with some
minimal default content, in reStructuredText format.

These docs must be "built" which generates HTML (or other formats) from the
reST source.  This is how you'll (re-)build docs from now on::

   cd ~/src/rattail-tutorial/docs
   make html

This will generate HTML within the ``_build`` folder underneath the docs
folder.  You can then view these docs e.g. with::

   firefox _build/html/index.html

Note that each time docs are built, it tries to avoid re-building things which
haven't changed since last build.  It sometimes may be helpful to "clean" the
docs build, i.e. wipe it out so the next build is forced to rebuild
everything::

   make clean
   make html

Now if you check your git status, you'll probably see the ``_build`` folder is
considered "untracked" by git.  However we don't want git to concern itself
with this folder at all, so we should ignore that, e.g. by doing::

   cd ~/src/rattail-tutorial
   echo 'docs/_build/' >> .gitignore
   git add .gitignore
   git commit -m "Ignore docs build folder"

And finally, there is another gotcha which you won't notice until you clone
your project's source repo to another location, and try to build docs there.
It's not a real big deal, but you may see a warning when the docs are building,
such as:

.. code-block:: none

   copying static files... WARNING: html_static_path entry '.../src/rattail-tutorial/docs/_static' does not exist

To prevent that, we'll add a stub file to our repo which will ensure that
folder always exists::

   cd ~/src/rattail-tutorial
   mkdir -p docs/_static
   touch docs/_static/.keepme
   git add docs/_static/.keepme
   git commit -m "Add stub file to prevent docs build warning"

Writing Some Docs!
------------------

Again it may not make sense for you to do much of this, at this point in the
game.

But while building this tutorial, all docs written up to this point have *not*
been part of the project's docs repo proper, but rather were created as simple
ad-hoc text files.  So our next step is simply to "transfer" all docs content
created thus far, from these ad-hoc files, into the project docs folder.

This was a pretty manual process, then at the end we commit all changes::

   cd ~/src/rattail-tutorial
   git add docs
   git commit -m "Transfer ad-hoc setup docs to tutorial project"