gerbera/doc

Overview

Gerbera uses Sphinx Python Document Generator to generate documentation.

Below you will find instructions on how to:

• Generate documentation
• View documentation
• Add to documentation
• Publish documentation

Prerequisite Python pip virtualenv

Install Python virtualenv using the pip virtualenv instructions

Generate Documentation

The Gerbera documentation uses a shell script to build the documentation with Sphinx.

$ chmod u+x ./do_sphinx.sh
$ ./do_sphinx.sh

To clear an existing _build directory

$ ./do_sphinx.sh --clobber

The script does the following activities:

• Creates a Python virtualenv under doc/_build/gerbera-env
• Installs Sphinx with Read-The-Docs theme
• Generates documentation using Sphinx

Output looks similar to below:

Example run using macOS High Sierra

bash-3.2$ ./do_sphinx.sh --clobber

Removing _build directory


Creating Gerbera documentation build directory /development/gerbera/doc/_build


Creating Gerbera Python virtualenv

Using base prefix '/usr/local/Cellar/python3/3.6.4/Frameworks/Python.framework/Versions/3.6'
New python executable in /development/gerbera/doc/_build/gerbera-env/bin/python3.6
Also creating executable in /development/gerbera/doc/_build/gerbera-env/bin/python
Installing setuptools, pip, wheel...done.

Installing Sphinx document genertor with sphinx_rtd_theme theme

Collecting Sphinx
  Using cached Sphinx-1.6.6-py2.py3-none-any.whl
Collecting sphinx_rtd_theme
  Using cached sphinx_rtd_theme-0.2.4-py2.py3-none-any.whl
Collecting docutils>=0.11 (from Sphinx)
  Using cached docutils-0.14-py3-none-any.whl
Collecting Jinja2>=2.3 (from Sphinx)
  Using cached Jinja2-2.10-py2.py3-none-any.whl
Collecting Pygments>=2.0 (from Sphinx)
  Using cached Pygments-2.2.0-py2.py3-none-any.whl
Collecting babel!=2.0,>=1.3 (from Sphinx)
  Using cached Babel-2.5.3-py2.py3-none-any.whl
Collecting requests>=2.0.0 (from Sphinx)
  Using cached requests-2.18.4-py2.py3-none-any.whl
Requirement already satisfied: setuptools in ./gerbera-env/lib/python3.6/site-packages (from Sphinx)
Collecting alabaster<0.8,>=0.7 (from Sphinx)
  Using cached alabaster-0.7.10-py2.py3-none-any.whl
Collecting sphinxcontrib-websupport (from Sphinx)
  Using cached sphinxcontrib_websupport-1.0.1-py2.py3-none-any.whl
Collecting imagesize (from Sphinx)
  Using cached imagesize-0.7.1-py2.py3-none-any.whl
Collecting six>=1.5 (from Sphinx)
  Using cached six-1.11.0-py2.py3-none-any.whl
Collecting snowballstemmer>=1.1 (from Sphinx)
  Using cached snowballstemmer-1.2.1-py2.py3-none-any.whl
Collecting MarkupSafe>=0.23 (from Jinja2>=2.3->Sphinx)
Collecting pytz>=0a (from babel!=2.0,>=1.3->Sphinx)
  Using cached pytz-2017.3-py2.py3-none-any.whl
Collecting idna<2.7,>=2.5 (from requests>=2.0.0->Sphinx)
  Using cached idna-2.6-py2.py3-none-any.whl
Collecting chardet<3.1.0,>=3.0.2 (from requests>=2.0.0->Sphinx)
  Using cached chardet-3.0.4-py2.py3-none-any.whl
Collecting certifi>=2017.4.17 (from requests>=2.0.0->Sphinx)
  Using cached certifi-2018.1.18-py2.py3-none-any.whl
Collecting urllib3<1.23,>=1.21.1 (from requests>=2.0.0->Sphinx)
  Using cached urllib3-1.22-py2.py3-none-any.whl
Installing collected packages: docutils, MarkupSafe, Jinja2, Pygments, pytz, babel, idna, chardet, certifi, urllib3, 
requests, alabaster, sphinxcontrib-websupport, imagesize, six, snowballstemmer, Sphinx, sphinx-rtd-theme
Successfully installed Jinja2-2.10 MarkupSafe-1.0 Pygments-2.2.0 Sphinx-1.6.6 alabaster-0.7.10 babel-2.5.3 
certifi-2018.1.18 chardet-3.0.4 docutils-0.14 idna-2.6 imagesize-0.7.1 pytz-2017.3 requests-2.18.4 six-1.11.0 
snowballstemmer-1.2.1 sphinx-rtd-theme-0.2.4 sphinxcontrib-websupport-1.0.1 urllib3-1.22

Build Gerbera Documentation

Running Sphinx v1.6.6
loading pickled environment... not yet created
building [mo]: targets for 0 po files that are out of date
building [html]: targets for 1 source files that are out of date
updating environment: 1 added, 0 changed, 0 removed
reading sources... [100%] index                                                                                                                                                
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
writing output... [100%] index                                                                                                                                                 
generating indices... genindex
writing additional pages... search
copying static files... WARNING: html_static_path entry '/development/gerbera/doc/_static' does not exist
done
copying extra files... done
dumping search index in English (code: en) ... done
dumping object inventory... done
build succeeded, 1 warning.

SUCCESS generated Gerbera documentation:

/development/gerbera/doc/_build/dist

View Generated Documentation

You can view the documentation by creating a static web server in Python.

Activate the virtualenv

$ source _build/gerbera-env/bin/activate
(gerbera-env) $

Deactive the virtualenv using deactivate command

(gerbera-env) $ cd _build/dist/
(gerbera-env) $ python -m http.server 8000

Visit the generated documentation using the server URL in a browser

http://localhost:8000

Add Documentation

The Sphinx document generator uses reStructuredText to generate the doucmentation.

First, take a look at the Sphinx reStructuredText Primer

Publish Documentation

TODO: