#######################
Documentation authoring
#######################

*****
Local
*****

Documentation generation and publishing
=======================================
To build html documentation locally, just run::

    make docs-html

    # open in browser
    open doc/build/html/index.html

    # on Linux
    xdg-open doc/build/html/index.html


******
Public
******

Automatic rebuild through ``git push`` event
============================================

To automatically publish the Sphinx-generated documentation to https://hiveeyes.org/docs/beradio/
when pushing to git@git.elmyra.de:hiveeyes/beradio.git, follow these steps:

- Add or enable key ``www-data@pulp`` at https://git.elmyra.de/hiveeyes/beradio/deploy_keys::

    ssh-rsa   www-data@pulp

- Add web hook for "Push events" at https://git.elmyra.de/hiveeyes/beradio/hooks with URL::

    https://gitlab:KoabMulp@docs.elmyra.de/hiveeyes/.gitlab-webhook

- Perform a push event to the repository or use the "Test Web Hook" button in GitLab

- The documentation should now be available at
  https://hiveeyes.org/docs/beradio/


Hook into your domain namespace
===============================
The base publishing address is https://docs.elmyra.de/hiveeyes/, where
https://hiveeyes.org/docs/beradio/ is pointing to as a http reverse proxy.

::

    <VirtualHost *:443>

        ServerName hiveeyes.org
        # [...]

        # reverse proxy to documentation platform
        SSLProxyEngine on
        <Location "/docs">
            ProxyPass https://docs.elmyra.de/hiveeyes/
            ProxyPassReverse https://docs.elmyra.de/hiveeyes/
        </Location>

    </VirtualHost>

- Access documentation at
  https://hiveeyes.org/docs/beradio/

