aggregate documentation

[nilshempelmann]

Action item from VC14

huard suggested: "I think we need a plan to aggregate documentation. Like a central repo that individual projects can draw from and synchronize with. I just don’t know how to do that. The cookie-cutter is a good place to start, since every bird should replicate the doc structure"

Related to: https://github.com/bird-house/birdhouse-docs/issues/30 https://github.com/bird-house/birdhouse-docs/issues/17 https://github.com/bird-house/birdhouse-docs/issues/6

[nilshempelmann]

opened the branch doc-aggregation and started with an descriptive overview.

[nilshempelmann]

@huard do you have a real example to find a best practise?

[huard]

Not really...

[nilshempelmann]

Intersphinx could be a way to go. https://www.sphinx-doc.org/en/master/usage/extensions/intersphinx.html But its for python code documentation. @huard you are looking for an aggregation of rst files from differnet repositories, right? Here is an overview of the documentation organisation: https://github.com/bird-house/birdhouse-docs/blob/doc-aggregation/docs/source/_images/Documentation_aggrgation.png

any comments?

[cehbrecht]

Intersphinx may help us to provide links to a common "static" documentation.

An alternative might be to use git submodules: https://git-scm.com/book/en/v2/Git-Tools-Submodules

You have a shared git repo with common doc parts ... but you would be able to customize them locally. But maybe that is to advanced.

[huard]

Given that some of the documentation is autogenerated from the live package, using submodules would mean that we need to install all the different birds in the same environment. That might be difficult. I think the intersphinx solution is cleaner and your proposal to organize the docs seems logical.

[nilshempelmann]

another option:

.. literalinclude :: https://raw.githubusercontent.com/Ouranosinc/pavics-sdi/master/docs/source/index.rst
   :language: rst

But recieved a 'not found' error for now

[nilshempelmann]

Here is a solution. Just for inspiration: https://stackoverflow.com/questions/6068296/inclusion-of-external-documentation-into-a-sphinx-project

[nilshempelmann]

@huard I might need your help to aggregate documentation:

working with .. literalinclude:: is not the solution:

WARNING: Include file '/home/nils/birdhouse/birdhouse-docs/docs/source/https:/ouranosinc.github.io/pavics-sdi/_sources/arch/backend.rst.txt' not found or reading it failed (in branch doc-aggregation)

If I got it right, the appropriate files needs to be fetcht and compiled into the main documentation

[nilshempelmann]

@huard I added an docaggregation extention to fetch files from extern documentaitons into the main birdhouse documentation. (branch doc-aggregation)

still some issues with code: exception: cannot import name 'directive_dwim' from 'sphinx.util.compat' (took the code from this example )

But this could be a way to go. Your opinion?

[huard]

Looking into it.

[huard]

Pushed a change that fixes it. One issue is that links to figures are broken. Maybe change the directive name to "gitinclude" or something like that.

[huard]

Added a gittoctree directive and renamed your directive to gitinclude. See the docstring for examples of use.

[nilshempelmann]

Nice Job!! We need to add a little hint in the developer section how to aggegate external documentation and gues that's it, right?

[nilshempelmann]

A way to aggregate documentation has been found: https://birdhouse.readthedocs.io/en/latest/dev_guide.html#writing-documentation.

Stepp forward, be realized in:

30

17

6