Project documentation

[sbellem]

Copied from original issue: amiller/HoneyBadgerBFT#26 and was originally concerned with "where to publish the docs", and has now been converted into a more general issue about documenting the project.

Overall, we could loosely follow the guidelines in https://docs.python-guide.org/writing/documentation/, as a starting point.

---

Maintaining a changelog

This is to document the project release history. We could simply follow the guidelines outlined in https://keepachangelog.com/.

As for the name of the changelog file, we may use CHANGELOG, or HISTORY.

If at some point we are super discipline with the git commit messages, we could consider automatically generating the changelog from the commit messages, using a tool such as https://github.com/vaab/gitchangelog.

Documentation structure

The following from https://docs.python-guide.org/writing/documentation/#project-publication may be useful as a starting point, and should be easy to extend to fit the documentation needs specific to this project.

Depending on the project, your documentation might include some or all of the following components:

• An introduction should show a very short overview of what can be done with the product, using one or two extremely simplified use cases. This is the thirty-second pitch for your project.
• A tutorial should show some primary use cases in more detail. The reader will follow a step-by-step procedure to set-up a working prototype.
• An API reference is typically generated from the code (see docstrings). It will list all publicly available interfaces, parameters, and return values.
• Developer documentation is intended for potential contributors. This can include code convention and general design strategy of the project.>

---

From @sbellem on August 19, 2017 21:38

Where to Publish the docs

Publishing on Read the Docs

It is very common for open source Python projects to host their documentation on Read the Docs.

It is usually relatively simple to set up.

There are some limitations however in terms of what can be installed beyond Python packages specified in a requirements.txt file, and running python setup.py install. This means that for libraries that require installing C header files for instance, it does not seem to be possible to instruct Read the Docs to perform those required installations. In other words, it does not seem to be possible to instruct Read the Docs to execute:

apt-get -y install libgmp-dev libmpc-dev
wget https://crypto.stanford.edu/pbc/files/pbc-0.5.14.tar.gz
tar -xvf pbc-0.5.14.tar.gz
cd pbc-0.5.14 && ./configure && make && make install
git clone https://github.com/JHUISI/charm.git
cd charm && git checkout 2.7-dev && ./configure.sh && python setup.py install

Since the above instructions are required before running python setup.py install to install honeybadgerbft, and installing honeybadgerbft is required in order to build documentation from the the docstrings, it is then not simple to set up the docs on Read the Docs.

Perhaps there are workarounds, such as indicated here, but this means it will take slightly longer to set up.

Publishing on Github Pages

Another approach would be to publish the docs on Github Pages. For a concrete example, one may look at the asyncpg project's travis-publish-docs.sh script.

[sbellem]

From @amiller on August 22, 2017 3:1

Let's defer this question of where to put it till resolving other issues, especially amiller/HoneyBadgerBFT#20. For now, while the code is in transition into a complete library, I'm most concerned about coming up with a process that leads to good documentation following the code.

[sbellem]

• Try out https://github.com/python-trio/sphinxcontrib-trio