Publish your documentation with ReadTheDocs.org

Prerequisites

Your doc is written :)

Prepare the configuration file for Sphinx

In the plugin repository, create a file docs/conf.py which contains:

import sys
import os

extensions = [
    'sphinx.ext.todo',
]

source_suffix = '.txt'

master_doc = 'index'

### part to update ###################################
project = u'domogik-plugin-diskfree'
copyright = u'2014, Fritz'
version = '0.1'
release = version
######################################################

pygments_style = 'sphinx'

html_theme = 'default'
html_static_path = ['_static']
htmlhelp_basename = project

Update the middle part depending on your plugin.

Create an account on RTD

If you don’t have an account, go on RTD and create an account

Add your plugin project to RTD

In the dashboard <https://readthedocs.org/dashboard/>, click on Import to add your plugin documentation.

Fill the form:

  • Name : put the full plugin name : domogik-plugin-myplugin.
  • Repo : put the github repository url : http://github.com/mygithublogin/domogik-plugin-myplugin.git
  • Repository type : Git or something else if you don’t use git
  • Description : your plugin description
  • Language : English
  • Documentation type : Sphinx html
  • Project url : empty
  • Canonical url : empty
  • Tags : domogik

Click on Create.

The build will be automatically started for the branch master. It may fail with the reason:

Conf file not found.

This is normal as the master branch contains no documentation (and no plugin code) if you are working on the first release of your plugin!

You will now need to activate the develop branch for your RTD plugin project.

Generate documentation for the develop branch

From the dashboard, for your plugin project, click on the Admin button. In the menu, go in Versions.

Set the develop version as Active. Uncheck the Active checkbox for the latest version and click on Submit.

You are now on the Overview page for your plugin project. The only version available is develop. You can click on Build to start the build of the documentation for the develop branch.

In the Builds menu for your project, you can check if the build was successful or not. If not, you can click on the status to get the error details.

You can now see the built documentation at http://domogik-plugin-myplugin.readthedocs.org/en/develop/ (adapt myplugin to your plugin name)

Notice that the View Docs button will send you to the latest version of your plugin documentation, which does not exists yet! This version will exists when your plugin will be stable and so, when you will have merge the develop branch in the master branch.

Set the hook to build the doc for each commit pushed

In your github project, you can set a hook to launch the documentation build on RTD for each commit pushed.

Go on your Github project url. For example https://github.com/mygithublogin/domogik-plugin-myplugin

  • Go in the Settings menu, then in Webhooks and services.
  • In the Services part, click on Add service and choose ReadTheDocs.
  • The ReadTheDocs service configuration page will be displayed. Check that Active is set and click on Add service.

Now, just do a documentation update, commit it and push it. You should see the doc updated a few minutes later.

Versions management

..todo ::
Continue :) * version management

i18n

..todo ::
TODO !

Read the doc :)

Your documentation is available at http://domogik-plugin-<plugin name>.readthedocs.org/en/<branch name>/. Example : http://domogik-plugin-teleinfo.readthedocs.org/en/develop/