Documentation for the GTRD database

Warning - under construction.

For developer

1. Install Shinx.
   pip install sphinx

2. Install Kroki - it allows to create different diagrams from text files
   pip install sphinxcontrib-kroki

3. Install recommonmark - it allows to use usual markdown for pages. So it is not needed to convert already written pages.
   pip install recommonmark

4. Install theme (now selecting for 2 variants 'typlog' or 'cloud')
   pip install sphinx-typlog-theme
pip install cloud_sptheme

5. make html - builds the project. You can open in the browser generated html files fro 'target' directory.

6. When you pull you chages int github, the documentation on readthedocs will be automatically rebuilded due to hit webhook.

7. Open link
   https://gtrd.readthedocs.io
   https://gtrd.rtfd.io

References

Sphinx

https://www.sphinx-doc.org/en/master/contents.html
https://www.sphinx-doc.org/en/master/usage/quickstart.html

RST

https://www.sphinx-doc.org/en/master/usage/restructuredtext/
https://thomas-cokelaer.info/tutorials/sphinx/rest_syntax.html
https://runawayhorse001.github.io/SphinxGithub/rtxt.html

Kroki - to build different diagrams

https://kroki.io/
https://github.com/sphinx-contrib/kroki

Markdown

http://recommonmark.readthedocs.org/
https://recommonmark.readthedocs.io/en/latest/auto_structify.html

https://github.com/ryanfox/sphinx-markdown-tables

Cloud theme

https://cloud-sptheme.readthedocs.io/en/latest/
https://cloud-sptheme.readthedocs.io/en/latest/lib/cloud_sptheme.ext.table_styling.html#module-cloud_sptheme.ext.table_styling

Alternatives

Diagrams - https://github.com/sphinx-contrib/plantuml

Markdown - https://myst-parser.readthedocs.io

Themes

• https://sphinx-themes.org/ - collection of Spinx themes
• sphinx-material - responsive Material Design theme
• sphinx-rtd-theme - official Read the Docs theme
• sphinx-typlog-theme - a sphinx theme designed by Typlog
• pydata-sphinx-theme - official PyData theme

Problems

Currently it is possible to build only HTML docs due to following error

  File "c:\python\python39\lib\site-packages\sphinx\writers\latex.py", line 2044, in unknown_visit 
  raise NotImplementedError('Unknown node: ' + node.__class__.__name__)
  NotImplementedError: Unknown node: kroki