123 lines
4.3 KiB
ReStructuredText
123 lines
4.3 KiB
ReStructuredText
|
|
.. 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"
|