We use Sphinx for documentation, and it's written in Python, so we'll setup a Python virtual environment.
If you are using pyenv to manage python versions, pick a python3 like:
pyenv local 3.6.3
Create a virtual environment:
virtualenv --python=python3 .venv3
Activate your virtual environment:
source .venv3/bin/activate
I manually installed Sphinx, then created a requirements requirements.txt file so you don't have install it; instead, install all the listed and versioned dependencies:
pip install -r requirements.txt
Then I ran the quickstart and took the defaults, except I used
docs
as my root path, and gave it my name and version number:
sphinx-quickstart
You won't have to run the quickstart, everything's in docs
.
To do it manually, you can build the docs by going into the docs
directory (with virtualenv activated) and use its Makefile to create a
HTML version:
cd docs make html
Then you can open up the _build/html/index.html file and see your beautiful docs. Ta da!
That creates standalone html files, but you can make a single large HTML with:
make singlehtml
whose output is in _build/singlehtml/index.html.
You can even make ePub with:
make epub
and find the output in _build/epub/ScaffoldingServerless.epub.
As a convenience (with virtualenv activated), in the top level directory, you can build all versions:
make docs
Edit the RST pages, as you wish, rebuild, and commit your builds if
you wish. If you add a new page, reference it from the index.rst file, omitting the .rst
extension.
Syntax and Configuration (in conf.py
are beyond the scope of this doc).