Python Design Documentation Part I: Goodbye ReadTheDocs, Hello GitBook

I don’t like the ReadTheDocs. When I was younger learning python2, readthedocs was popular because it compiled from docstrings with examples and allowed developers to making tech and design docs easy to give to others.

I picked up on the same thing with my first software, Cocktail Shaker.

Welcome to Cocktail Shaker's documentation! - Cocktail Shaker 1.0.0 documentation

It was cool for me to do the first time but over time I really started to dislike the standard imposed on my documentation because it didn’t fit my design. The things I disliked the most are:

• Format of the Docstrings
• Compiling Documentation
• User Interface

Docstrings

I hated the format of the doc-strings required for auto compilation imposed by sphinx, it felt robotic and didn’t look friendly to an average developer:

"""[Summary]

:param [ParamName]: [ParamDescription], defaults to [DefaultParamVal]
:type [ParamName]: [ParamType](, optional)
...
:raises [ErrorType]: [ErrorDescription]
...
:return: [ReturnDescription]
:rtype: [ReturnType]
"""

After writing my code and testing it continously I couldn’t handle this format and started developing my own, for example:

def shake(self, store_as_pickle = False, compound_filters = []):

    """

    Generate all combinations of a molecule
    
    Arguments:
        store_as_pickle (Bool): If the user wants to store the results into a pickle file.
        compound_filters (List): List of filters that the user would like to apply to their library.
    
    Returns:
        results (List): List of compounds generated into SMILES format.
    
    """

Unfortunately, this didn’t bode will for compilation and I did have to convert my docstrings into rst manually.

Compilation

I was not a fan of this. I understand the versaility of MakeFiles but doesn’t mean I like using them. When compiling the docs from rst to html into the appropiate format for sphinx can prove to be cumbersome and just another step in the workflow of updating documentation with some technical skill involved which leaves more work for the developer to understand:

# Minimal makefile for Sphinx documentation
#

# You can set these variables from the command line.
SPHINXOPTS    =
SPHINXBUILD   = python3 -msphinx
SPHINXPROJ    = CocktailShaker
SOURCEDIR     = source
BUILDDIR      = build

# Put it first so that "make" without argument is like "make help".
help:
 @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

.PHONY: help Makefile

# Catch-all target: route all unknown targets to Sphinx using the new
# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
%: Makefile
 @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

User Interface

I did not like the design. I feel like I could have created something better or more slick. I am sure they have updated it but I need something new and shiny.

So if I want to make the switch into a new documentation then I would need some requirements.

• A user interface that is cool and slick. It must be easily malleable.
• Low to no code. I don’t want to write code and have it deploy with a make file. I would like something more smoother where any developer can edit with minimal technical skill.
• Perhaps compatible with my doc-string format or have an ability.

2/3 I was able to achieve in a platform called Gitbook. The design layout was relatively simple.

I liked the big titles and big links on the left handside. I wrote the quickstart documentation first:

And immediately it looked pretty where I could have the code and the output in tabs. It allowed for a lot of slick design and allowed users to see how the code was tested. I also started using the tabs for explaining any algorithms in the code with images. This I think change the game for me. I could drag stuff from powerpoint into these tabs and give users information they needed. The flexibility of this platform reeled me in.

A key component of any software especially going through compliance is presenting the documentation in a suitable format to the governing body with version control.

This is the feature that really sold me. Converting all your documentations to PDF can be a pain. Having a feature built-in like this saves you a lot of time down the road.

With one touch of a button after writing I can synchronize with the Github Repository and publish with public url.

The platform itself is going to be my future host for python documentation moving forward because it gives me the flexibility to incorporate different type of documentation needed for design that is difficult to achieve with ReadTheDocs.

I think it allows me to be more succinct with my users and also make it more fun.

In Part II, I will talk about the synchronization of Gitbook with Github.