Status

Overview of Vircadia's User Documentation Tools

For Vircadia'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.vircadia.com.

Please take a moment to thank or donate to the active maintainers of this repository! ❤️

Translate

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

The recommended way is to use https://weblate.vircadia.dev.
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.

Run cmd as an administrator.

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

Install Python 3 via Chocolatey via cmd:
```
C:\> choco install python
```
Restart cmd as an admin or refresh with the command:
```
C:\> refreshenv
```

Install Sphinx video addon:

C:\> pip install git+https://github.com/vircadia/video.git

Install Sphinx version 3.x.x in a command line:
```
C:\> pip install -U Sphinx==3.5.4
```
Install the Markdown parser MyST-Parser:
```
C:\> pip install --upgrade myst-parser
```
Install our Sphinx theme:
```
C:\> pip install sphinx_rtd_theme
```

Compile Vircadia Documentation Locally

Fork and clone https://github.com/vircadia/vircadia-docs-sphinx.
Using a command line, cd to your local repository, then cd to the "docs" folder within it.
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

digisomni/vircadia-docs-sphinx