Tutorial Mkdocs & Readthedocs

As soon as you have a repository, you might be interested to embed quickly and easily some documentation. At this level:

  • Priviledge Markdown-based documentation since the corresponding files are:

Setting up a wiki can seems overkilling to display just a couple of notes, yet there exist some nice Git-based Markdown Wiki projects: Gollum, as embedded in GitLab, and Mkdocs. The main advantage of both tools is the possibility to serve the HTML rendering of the pages locally.

My personal preference goes to Mkdocs. The main reason is that Read the Docs, a web service dedicated to documentation management for the open source community, can natively interpret your configuration and offer an online rendering of the served pages for any public project – the this page for instance. Even more importantly, the Read the Docs site for your project will be automatically rebuilt upon every commits pushed on Github etc.

Here are a few notes to share my experience with these tools.

Mkdocs Installation and Usage

Reference:

Mac OS X

Assuming you have Homebrew installed:

$> brew install python3
$> pip3 install mkdocs

Linux (Debian / Ubuntu / CentOS … )

The packaged version of Mkdocs ({apt-get | yum} install mkdocs), is rather old. To use the latest version (0.17.0), follow these instructions:

$> pip install --user mkdocs
# Adapt your PATH and PYTHONPATH environment variables
# Add this in your favorite shell config
export PYTHONPATH=$HOME/.local/lib/python2.7/site-packages:$PYTHONPATH
export PATH=$HOME/.local/bin:$PATH

Windows

Follow the instructions provided on this tutorial. In particular, install Chocolatey and use it to install pip and mkdocs

$> choco install pip
$> pip install mkdocs

Mkdocs usage

To initialise a project with mkdocs, just run the following command from the root directory of your repository:

mkdocs new        # initialize 'mkdocs.yml' and docs/ directory

Then you just need to edit the mkdocs.yml file to reflect the left menu you wish to offer, with relative paths from the docs/ directory toward the markdown file you want to display:

# mkdocs.yml -- MkDocs configuration, all *.md files relative to docs/
site_name: UL HPC Developpers Documentaion
pages:
- Home: 'index.md'
- Tools:
    - SSH: 'tools/ssh.md'
    - Git: 'tools/git.md'
- Configuration:
    - CA Certificates: 'config/certificates/README.md'
theme: readthedocs

Note that you can also create sym-links within the docs directory

You can preview your documentation from the project root by running:

# run a local webserver automatically updated upon file changes
$> mkdocs serve   # ... and visit http://localhost:8000

# To use another port than the default 8000:
$> mkdocs serve --dev-addr localhost:8080

Again, all changes in the markdown sources will be taken into account dynamically.

You can build the full documentation locally by running mkdocs build.

Readthedocs

Read the Docs (RTFD for short) is defined as follows:

Read the Docs hosts documentation, making it fully searchable and easy to find. You can import your docs using any major version control system, including Mercurial, Git, Subversion, and Bazaar. We support webhooks so your docs get built when you commit code.

So assuming you have a project named <name> (under repository <name> typically), you probably want it to be served as <prefix>-<name>.readthedocs.org (since potentially several people might have their own implementation of the <name> project eventually served on RTFD), the setup of the documentation shall be done as follows:

First on Github:

  • on your project page i.e. https://github.com/<login>/<name>, configure the binding to readthedocs as follows:
    • Go to Settings / Integrations & services, select “Add service” and select ‘ReadTheDocs’.

Now on Read the Docs

  • Login as <login> on Read the Docs
  • Go on the import page and select a MANUAL import
  • Feed the project details:
    • Name: <login>-<prefix>-<name> (adapt <name> accordingly)
    • Repository URL: https://github.com/<login>/<name>
    • Repository type: Git
    • check ‘Edit advanced project options’
  • Feed the (advanced) Project Extra Details:

    • Enter a description – most probably the one you placed as a description of the Github project, or in metadata.json for a Puppet module etc. Ex from the ULHPC/puppet-sudo:

      `ULHPC/sudo <https://github.com/ULHPC/<prefix>-sudo>`_ is a Puppet module to manage sudo and sudoers files.
 This module is also released on the `Puppet forge  <https://forge.puppetlabs.com/ULHPC/sudo>`_
    • Documentation type: Mkdocs (Markdown)
    • Programming Language: Ruby (adapt accordingly – this is the setting for a puppet module)
    • Project homepage: https://github.com/<login>/<name>
    • Tags: <prefix>, <name> (complete as appropriate)
  • Now you can customize the configuration by selecting the Admin tab on the newly created project.
    • Under Admin/Settings: change the name to a comprehensive subject **<Prefix> <name> and re-enter the tags. Submit your changes.
    • Under Admin/Advanced Settings: enter the Default branch (devel) to be used for the latest doc generation. Submit your changes.
    • Under Admin/Versions, you might wish to activate the production branch. Submit your changes.
    • Under Admin/Redirects, add a Prefix Redirect rules from the URL /docs/. Submit your changes.
    • Under Admin/Notifications, add the hpc-sysadmins@uni.lu email.

Finally you can now adapt the README.md of the project to add the new badge.