Documentation

More documentation is always appreciated and it’s something that you can contribute to from the GitHub web interface. This might be a great start point if you are new to Open Source and GitHub!

Things that we need help with:

  • More documentation. Something that you think is unclear?

  • More examples of how to use opsdroid

  • More Tutorials

  • Typos/Grammar check

  • Blog posts, articles, etc

  • Any issue marked with the documentation tag

Building the docs

Opsdroid’s documentation is built using Sphinx with the Recommonmark and Napoleon plugins and is hosted on readthedocs.

You can build the documentation yourself locally and view them using the built in Python web server.

$ tox -e docs  # or `sphinx-build -b html docs/ docs/_build/`
The HTML pages are in docs\_build.

$ cd docs/_build && python -m http.server
Serving HTTP on 0.0.0.0 port 8000 (http://localhost:8000/) ...

Writing documentation

All documentation should be written in Basic English where possible. We should try to keep words, phrases and grammar as simple as possible to make the project as accessible as possible.

Markdown is our preferred markup language, although reStructuredText (rst) is also supported. You may also embed portions of rst within your markdown documentation with the following syntax:

```eval_rst
.. warning::
   This is a warning admonition from rst within a markdown document.
   Useful because markdown doesn't have warnings.
```

Renders as:

Warning

This is a warning admonition from rst within a markdown document. Useful because markdown doesn’t have warnings.

You can also use Sphinx autodoc directives to embed docstrings from the opsdroid module within your markdown documentation too.

```eval_rst
.. autofunction:: opsdroid.matchers.match_event
```

Renders as:

opsdroid.matchers.match_event(event_type, **kwargs)

Return event type matcher.

Decorator that calls skill based on passed event_type.

Parameters
  • event_type (str) – opsdroidstarted, message, typing, reaction, file, image

  • **kwargs (dict) – arbitrary kwargs to be added to the event matcher

Returns

Decorated function

It is preferable to keep as much documentation within docstrings in the opsdroid codebase as possible and to include it in the documentation website using autodoc.