Getting Started

doc-wizard

doc-wizard is a tool to set up a gitlab project with documentation. It creates a docs directory, where it sets up a Sphinx documentation tree from a template. It also updates or creates a .gitlab-ci.yml file such that the gitlab ci builds and deploys the documentation whenever theres a push.

Installation

To install doc-wizard, simply run:

$ pip install doc-wizard

Basic Use

To create documentation for your gitlab project, first cd into the base directory of the project. For a default setup, such as the one used in this documentation, simply run:

$ doc-wizard

Now that the template has been created, there will be a docs/ directory and a .gitlab-ci.yml file at the base of your project. In the docs/ directory, there is a file called source/getting_started which contains a sample section label and section title under a chapter title. Each new section title should have above it a label in the format:

and should itself have the format:

There can be as many sections in a source file as you need. To add text to the sections, simply start typing on the line below the section header.

Now to view the documentation, type:

$ make html

from the docs/ directory. Now, open docs/build/html/index.html in your web browser to view a sample of your documentation!

If you would like more chapters in your documentation, simply add a new .rst file in source/, then update index.rst to have:

source/(new chapter).rst

specified as a source file.

Other Options

doc-wizard includes a few command line options to customize the template.

Options:

-t, --theme TEXT

Specify the theme to use for the docs. Must be a pip-installable Sphinx theme. Defaults to “alabaster”

--no_template

Set if you do not want a doc template to be generated. Set if you already have a Sphinx docs directory with documentation.

-d, --doc_dir TEXT

Directory in which doc templates will be generated. Defaults to “docs”

-n, --name TEXT

The name of the project. It will be used in the template documentation. Defaults to the current working directory.

-a, --autodoc TEXT

Directory where the modules are, relative to project base. If provided, autodoc will be enabled and Sphinx will parse the docstrings in the modules

The most notable of these is the autodoc option. Sphinx has an autodoc module which reads source files specified in references.rst and creates a reference page in the documentation using docstrings. To have doc-wizard set up the documentation for autodoc automatically, specify the directory, relative to the base of the project, in which all your project modules are. If you have well formatted markdown docstrings, autodoc will then geneerate a reference section for you documentation.

Hosting Your Docs

doc-wizard sets up the gitlab-ci to build and deploy your documentation whenever you push. Ordinarily, this would be enough, and your documentation would be available at the site shown in settings>pages of your project. With CERN, though, one more step is needed. First, go to webservices and create a domain for your documentation. Now, go to settings>pages and uncheck the “Force HTTPS” box. Save changes, then click “New Domain” and paste your domain, without the leading https:// or the trailing / into the box. Now your documentation should be hosted at that domain.