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
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/) ...
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. ```
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 ```
- opsdroid.matchers.match_event(event_type, **kwargs)
Return event type matcher.
Decorator that calls skill based on passed event_type.
event_type (str) – opsdroidstarted, message, typing, reaction, file, image
**kwargs (dict) – arbitrary kwargs to be added to the event matcher
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.