/BioUML-docs

Multilingual documentation for BioUML platform

Primary LanguagePythonGNU Affero General Public License v3.0AGPL-3.0

BioUML-docs

The BioUML platform documnetation in Еnglish and Russian

For developer

  1. Install Shinx.
    pip install sphinx

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

  3. Install Sphinx extension for rendering markdown tables.
    pip install sphinx_markdown_tables

  4. Install Read the Docs theme
    pip install sphinx-rtd-theme

  5. Install sphinx-intl
    pip install sphinx-intl

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

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

  8. Open link
    https://biouml.readthedocs.io
    https://biouml.rtfd.io

Internationalization

  1. Create pot files. They will be located in .\build\gettext directory.
    make gettext

  2. Create or update po files for English.
    sphinx-intl update -p build/gettext -l ru

  3. Translate in Weblate

  4. To create translated vesrion
    make -e SPHINXOPTS="-D language='ru'" html


For Windows cmd.exe, run:
set SPHINXOPTS=-D language=ru
make html

PDF

PDF file can be generated by 2 ways:

  1. By ReadTheDocs, it is specified in .readthedocs.yaml

  2. By Sphinx-SimplePDF
    https://sphinx-simplepdf.readthedocs.io

For Sphinx-SimplePDF

  1. Install Sphinx-SimplePDF
    pip install sphinx-simplepdf

  2. For Windows - install GTK
    https://github.com/tschoonj/GTK-for-Windows-Runtime-Environment-Installer/releases

  3. To build pdf
    make simplepdf

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

Internationalization

https://www.sphinx-doc.org/en/master/usage/advanced/intl.html
https://docs.weblate.org/en/latest/devel/sphinx.html