README.md

Status

Overview of Overte's User Documentation Tools

For Overte's user documentation system, we use Sphinx to generate it, and a web server to publish/host it. GitHub is a helpful middleman and stores all of the docs.

Sphinx is an open-source, robust solution for software documentation that includes features that writers expect, like:

• Single Source Publishing (HTML, PDF, ePub, and more)
• Content reuse through includes
• Multiple mature HTML themes that provide great user experience on mobile and desktop
• Referencing across pages, documents, and projects
• Index and Glossary support
• Localization support

Our main documentation is hosted at https://docs.overte.org.

Translate

There are two ways to help with the translation of Overte's documentation:

• The recommended way is to use Weblate.
• You can also submit updated .po files via a pull request.

Please contact Julian Groß or open an issue if you want to translate a language that is not in the system yet.

Install Sphinx for Local Builds (Windows)

We encourage you to compile the documentation locally on your computer prior to submitting a PR. To install Sphinx:

Note: You will need git installed and available to your cmd.

1. Run cmd as an administrator.

2. Install Chocolatey via the cmd (on one line):

   @"%SystemRoot%\System32\WindowsPowerShell\v1.0\powershell.exe" -NoProfile -InputFormat None -ExecutionPolicy Bypass -Command "iex ((New-Object System.Net.WebClient).DownloadString('https://chocolatey.org/install.ps1'))" && SET "PATH=%PATH%;%ALLUSERSPROFILE%\chocolatey\bin"
   

   If you run into any problems with this command, please take a look at https://github.com/chocolatey/choco/wiki/Troubleshooting

3. Install Python 3 via Chocolatey via cmd:

   C:\> choco install python
   

4. Restart cmd as an admin or refresh with the command:

   C:\> refreshenv
   

5. Install all requirements:

   C:\> pip install -r requirements.txt
   

Compile Overte Documentation Locally

1. Fork and clone https://github.com/overte-org/overte-docs-sphinx.
2. Using a command line, cd to your local repository, then cd to the "docs" folder within it.
3. Compile with the command make html.

The HTML output will be in build\html. Open home.html in a browser to view the docs.

To compile a different language you need an additional set of commands:

• make gettext creates gettext files.
• sphinx-intl update -l xX will create/update the .po translation files.
• make SPHINXOPTS="-Dlanguage=xX" html compiles the selected language.

Replace xX with your language code

Using RST

Most of our docs use RST. reStructuredText (RST) is the default plaintext markup language used by Sphinx. It is an extensible markup language, that is fully customizable. To learn more, refer to Sphinx's reStructuredText Primer. RST should be used for any real documentation, as Markdown only supports very basic directives. The MyST parser expands Markdown significantly, but RST should still be preferred as writers and translators would need to learn two big markup languages instead of just one. A valuable resource for RST is the official documentation.

Using videos

The muted property is needed for autoplay to work in Chrome.

Format & Conversion

When adding videos to the documentation, it is important to use H.264 and VP9 to ensure that they can be played in all major web browsers.

To convert videos and animated images to VP9 you can use following command in ffmpeg:

ffmpeg -i INPUTFILE -c:v libvpx-vp9 -b:v 0 -crf 5 -vf "scale=-2:'min(600,ih)'" -cpu-used 5 -row-mt 1 -c:a libopus -b:a 96K _static/videos/OUTPUTFILE.webm

And to convert to H.264:

ffmpeg -i INPUTFILE -c:v libx264 -b:v 0 -crf 18 -vf "scale=-2:'min(600,ih)'" -c:a libfdk_aac -b:a 96K _static/videos/OUTPUTFILE.mp4