Develop doc

[mexanick]

Add some documentation, not yet complete, but sufficient to serve as a template/example

Description

Few modules documented, automated tools for documentation has been included in CI routine.

Types of changes

• [ ] Bug fix (non-breaking change which fixes an issue)
• [x] New feature (non-breaking change which adds functionality)
• [ ] Breaking change (fix or feature that would cause existing functionality to change)

Motivation and Context

We need proper docs

How Has This Been Tested?

Tested locally + travis-docker CI routine

Screenshots (if appropriate):

Checklist:

• [x] My code follows the code style of this project.
• [ ] My change requires a change to the documentation.
• [x] I have updated the documentation accordingly.
• [x] I have added tests to cover my changes.
• [x] All new and existing tests passed.

[mexanick]

Reason for reg_utils/doc rather than reg_utils/python//doc?

Few reasons:

• we will have also the c++ part (going to start migration off of this PR) for which I'd like to integrate the documentation as well
• we have an overhead with introduction which is for both packages (yet has to be properly filled as well as the reg_generator doc)
• actually, the docstrings themselves are in python source files, it is only general story-like documentation plus some config is upstream
• and finally reg_interface and reg_generator are subpackaged and latter will dependent on the former

What is the purpose of the multiple .gitignore files in the doc tree structure? Better to have the Makefile create the necessary (currently empty) directories (e.g., _build, _templates, _static) for the docs, and not have them part of the repository

This two questions are connected. I didn't modify the default Makefile created by sphinx, so that's why I added .gitignores (required to keep folder structure in the repository). I'll look into this. Let me know if you have a ready solution

[mexanick]

I thought a new push will restart the CI build... However I found it cancelled and had to restart it manually. Is it expected? Is it possible to change this kind of behavior to automatically restart the build check when new commits arrive?

[jsturdy]

The current setting is to trigger a build on all push and pr events; a more recent push will cancel the previous build, so your new push should have triggered a new build, but there can be problems if too many events come in quick succession, i.e., a tag and push event arrive because you did:

git add <changed files>
git ci -m "something changed"
git tag -a -m "note about new tag" vx.y.z
git push origin # pushes commits and tags

In cases like this, I've seen the branch build triggered, but not the tag build...

[mexanick]

gitignores are removed. Yes, the sphinx makefile is generic and your suggestion can be implemented. Could you advise how to do that?

[jsturdy]

You can try usual git commands: git mv path/to/sphinx/Makefile config/mfSphinx.mk

Then for the inclusion I'll have to take a closer look Could try in the package Makefile, add a line

include $(BUILD_HOME)/$(Project)/config//mfSphinx.mk

And then let the package Makefile drive the whole process (no Makefile in the doc subdir)

I think this would be best, but I'm not sure if there's not some small roadblock I've missed Missed that it's looking for conf.py in the directory from where sphinx-doc is called. Adding:

# You can set these variables from the command line.                                                                                                                                                                                                                              
DOCBASE     = $(PackagePath)/doc
SPHINXOPTS  =
SPHINXBUILD = sphinx-build
PAPER       =
SOURCEDIR   = $(DOCBASE)/
BUILDDIR    = $(DOCBASE)/_build

# Internal variables.                                                                                                                                                                                                                                                             
PAPEROPT_a4     = -D latex_paper_size=a4
PAPEROPT_letter = -D latex_paper_size=letter
ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) $(SOURCEDIR)
# the i18n builder cannot share the environment and doctrees with the others                                                                                                                                                                                                      
I18NSPHINXOPTS  = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) $(SOURCEDIR)

and changing the clean target to cleandoc in the new mfSphinx.mk seems to do the trick, but I didn't test in a virtualenv with the package installed, so there's probably one or two other nuances that need sorting out.

[mexanick]

The problem with running sphinx build correctly is fixed, however autodoc still fails to import because of missing libraries. I propose to merge this PR and fix doc building in the next PR, where the libraries will be added.