Sphinx Documentation

[joshuaskelly]

Overview

We really should have documentation for our project and Sphinx seems the way to go.

http://www.sphinx-doc.org/en/stable/

[PythooonUser]

I could have a look at that, if you like. It primarily means to convert the doc strings in a usable form, I guess.

[joshuaskelly]

Sure! Go ahead and look into this. I've never dealt with it before so excited to see how it works.

[PythooonUser]

I tried to include the README.md in the documentation, but apparently I couldn't get it to work. There seems to be a way, but it's not working for me.

http://www.sphinx-doc.org/en/stable/markdown.html http://recommonmark.readthedocs.io/en/latest/auto_structify.html

I tried in conf.py:

from recommonmark.transform import AutoStructify
from recommonmark.parser import CommonMarkParser

# For MARKDOWN support
def setup(app):
    github_doc_root = 'https://github.com/JoshuaSkelly/twitch-observer/tree/features/sphinx-documentation/docs'
    app.add_config_value('recommonmark_config', {
            'url_resolver': lambda url: github_doc_root + url,
            'auto_toc_tree_section': 'Contents',
            }, True)
    app.add_transform(AutoStructify)

And in index.rst:

.. include:: ../README.md

Which produces:

Maybe you have an idea. I have never worked with Sphinx before aswell.

[PythooonUser]

Removed the broken flavoured markdown support with 67e792c4f5bd5f478f4e52128f3aef91dcac6008.

[PythooonUser]

Question:

• Do we want to add all the content of the README to the documentation?
• Do we want to structure the content into several sections?
• Do we only want to include the autogenerated module documentation?

[joshuaskelly]

Answers:

1. I don't think so.
2. I think breaking content into several sections makes it more accessible.
3. Perhaps? I think the goal of this feature is to have nice API documentation.

[joshuaskelly]

I've created a ReadtheDocs.org account and hooked up the repo! 😄

[PythooonUser]

Does that mean we have to reference the index.rst on readthedocs.org and then it's fine?

[joshuaskelly]

Yeah. I think I just point readthedocs.org to our index.rst and the rest is magic.

[joshuaskelly]

Also looks like you have the use_color change in your documentation branch? Should remove that.

[PythooonUser]

Upsi. Apparently I didn't clean my repo properly when switching branches.

[PythooonUser]

Is there something else you want to add to the documentation? I guess I'm finished. See PR #43.