Automated build of documentation

[vlcinsky]

Why I want automated build of filedepot doc

Currently I have discovered zealdocs (clone of Dash.app) providing excellent access to technical documentation. One can search through it and read it even when offline. Apart from basic documentation set it allows adding more documentation sets by means of doc2dash tool allowing to convert HTML doc built by sphinx into Dash.app format.

For that reason I collected my favourite packages and added their documentation into my collection of documentation sets.

Difficulties to build doc

With many python packages the doc build procedure is very simple, often one single call to tox -e docs or something similar.

In case of filedepot I had to:

• create virtualenv to keep my global python environment clean
• install sphinx into it
• run few times make html to learn, what python packages shall be installed (I added boto, boto3, mongo, ming, pillow and possibly some more)
• finally succeed with doc build without errors.

Proposed solution

• Add tox.ini.
• Create tox environment docs so that one can build the docs by tox -e docs. The environment would not be run by default with simple tox invocation (not listing docs in top section listing envs to run).
• Complete the docs environment by adding all dependencies needed to build the docs properly.

If such modification is invited, I can create PR.

[amol-]

I don't think tox for this case would really be requirement, what you are describing as your major problem was the lack of a [doc] extra dependency into the depot package. Which I think would be a good addition, but as you already proposed tox introduction for testing, using it for docs too it's perfectly fine.

[vlcinsky]

I consider tox as great tool for automated creation of virtual environments and running some tasks in them. You are right, that I was missing sphinx dependency but as it does not belong to man package requirements (as it is not needed for using in production), separate requirements seem reasonable solution. Apart from sphinx the doc build was also missing other packages (mentioned above) where I am not sure if they belong to main package or into doc build as extra dependency. Anyway, I will create PR for it, it shall be rather easy.

[amol-]

TOX support for building docs was merged in https://github.com/amol-/depot/pull/42