We are about to finish this tutorial on how to create a Cookiecutter template for an Android application running Kivy. If you haven’t checked out Create Your Own Cookiecutter and Extending Cookiedozer yet, please have a brief look into these articles as this post draws on them.
The current project structure of Cookiedozer is as follows:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 |
cookiedozer/ ├── cookiecutter.json ├── {{cookiecutter.repo_name}} │ ├── {{cookiecutter.repo_name}} │ │ ├── {{cookiecutter.app_class_name}}.kv │ │ ├── {{cookiecutter.repo_name}}.py │ │ ├── __init__.py │ │ └── main.py │ ├── LICENSE │ ├── MANIFEST.in │ ├── README.rst │ ├── setup.py │ └── tests │ └── test_{{cookiecutter.repo_name}}.py ├── cookiedozer01.png ├── cookiedozer02.png ├── hooks │ └── post_gen_project.py ├── LICENSE └── README.rst |
Set up Sphinx
Following the instructions of the ReadTheDocs tutorial, we are going to create a docs folder at the template level.
|
1 2 |
$ cd cookiedozer/\{\{cookiecutter.repo_name\}\}/ $ mkdir docs |
Quickstart
Sphinx comes with a very handy CLI tool to set up docs, namely sphinx-quickstart.
|
1 2 |
$ cd docs $ sphinx-quickstart |
We can simply feed the Cookiecutter variables to it. Feel free to change the values according to your needs.
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 |
> Root path for the documentation [.]: <ENTER> > Separate source and build directories (y/n) [n]: y > Name prefix for templates and static dir [_]: <ENTER> > Project name: {{cookiecutter.app_title}} > Author name(s): {{cookiecutter.full_name}} > Project version: {{cookiecutter.version}} > Project release [{{cookiecutter.version}}]: <ENTER> > Source file suffix [.rst]: <ENTER> > Name of your master document (without suffix) [index]: <ENTER> > Do you want to use the epub builder (y/n) [n]: <ENTER> > autodoc: automatically insert docstrings from modules (y/n) [n]: y > doctest: automatically test code snippets in doctest blocks (y/n) [n]: n > intersphinx: link between Sphinx documentation of different projects (y/n) [n]: y > todo: write "todo" entries that can be shown or hidden on build (y/n) [n]: n > coverage: checks for documentation coverage (y/n) [n]: n > pngmath: include math, rendered as PNG images (y/n) [n]: n > mathjax: include math, rendered in the browser by MathJax (y/n) [n]: n > ifconfig: conditional inclusion of content based on config values (y/n) [n]: y > viewcode: include links to the source code of documented Python objects (y/n) [n]: n > Create Makefile? (y/n) [y]: y > Create Windows command file? (y/n) [y]: n |
Index.rst
Sphinx creates an index.rst file inside of the source folder which should look similiar to the following:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 |
.. {{cookiecutter.app_title}} documentation master file, created by sphinx-quickstart on Thu Jan 29 23:09:48 2015. You can adapt this file completely to your liking, but it should at least contain the root `toctree` directive. Welcome to {{cookiecutter.app_title}}'s documentation! ====================================================== Contents: .. toctree:: :maxdepth: 2 Indices and tables ================== * :ref:`genindex` * :ref:`modindex` * :ref:`search` |
Adding more pages to the docs is fairly easy. You just need to create another rst file and insert it to the table of contents respectively.
Readme and App Docs
In this particular case I reuse the readme which we created in the course of Create Your Own Cookiecutter as well as a separate file for our basic application.
|
1 2 3 |
$ cd source $ touch readme.rst $ touch {{cookiecutter.repo_name}}.rst |
Including the readme is very straight-forward. Simply add the following code.
|
1 2 3 |
.. _readme: .. include:: ../../README.rst |
The actual content of the app file is going to be generated from the python source code. To tell sphinx what to include edit {{cookiecutter.repo_name}}.rst as follows:
|
1 2 3 4 5 6 7 8 9 10 |
{{cookiecutter.repo_name}} Package ================================== :mod:`{{cookiecutter.repo_name}}` Module ---------------------------------------- .. automodule:: {{cookiecutter.repo_name}}.{{cookiecutter.repo_name}} :members: :undoc-members: :show-inheritance: |
Next up we update index.rst accordingly. In addition to the newly created pages we add the project’s short description using Cookiecutter.
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 |
.. {{cookiecutter.app_title}} documentation master file, created by sphinx-quickstart on Thu Jan 29 23:09:48 2015. You can adapt this file completely to your liking, but it should at least contain the root `toctree` directive. Welcome to {{cookiecutter.app_title}}'s documentation! ====================================================== {{cookiecutter.short_description}} Basics ------ .. toctree:: :maxdepth: 2 readme .. _apiref: API Reference ------------- .. toctree:: :maxdepth: 2 {{cookiecutter.repo_name}} Indices and tables ================== * :ref:`genindex` * :ref:`modindex` * :ref:`search` |
Package Location
There is one thing left to do. The autodoc extension needs to know where to find our package. It turns out conf.py already features an according example. We need the sys path to contain the folder two levels above the source folder.
|
18 19 20 21 |
# If extensions (or modules to document with autodoc) are in another directory, # add these directories to sys.path here. If the directory is relative to the # documentation root, use os.path.abspath to make it absolute, like shown here. sys.path.insert(0, os.path.abspath('../..')) |
Google Style Docs
As you might remember from the last part of this tutorial I used a doc string syntax in our tests module which is slightly different from the standard sphinx docs. Generally I prefer this over the regular syntax as it is way more readable and requires less boilerplate, but in this particular case I stick to the standard as I want the Kivy docs to seamlessly integrate with my docs.
At the end of the day it’s totally up to you if you want to use it for your project.
Feel free to consult the examples at http://sphinx-doc.org/latest/ext/example_google.html. Please note that you need to install an extension, namely Napoleon, for sphinx to understand Google Style docs.
That’s it for the documentation part. On the next page of this tutorial we are going to set up Buildozer as well as a MAKEFILE.
