Transfer ad-hoc setup docs to tutorial project

docs/start-docs.rst

@@ -0,0 +1,122 @@
+
+.. 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"