Discussion: documentation

[AartGoossens]

I'd like to start with proper documentation asap. I think updating/fixing the readme could be a quick start but after that I want to start with more extensive documentation. This issue is for discussing the approach.

Examples of documentation

Good examples

• https://vcrpy.readthedocs.io
• https://pandas.pydata.org/pandas-docs/stable/

Not so good examples

• https://docs.scipy.org/doc/numpy/

Tools

I like the combination of Sphynx to write/generate the documentation and Read the Docs to host it. Information on how to get started with this combination can be found here. An alternative is to use the GitHub wiki or Github pages to write and host the code. In general I like having the documentation in the same repository as the code: new features and their documentation can be part of 1 commit/PR.

Discussion points

• Are there other tools for writing/generating documentation?
• Do we want the docs in the same repo as the code?
• Do we prefer plain api documentation (more like numpy/pandas) or more written documentation with examples (like vcrpy)?

[sladkovm]

I also like Sphynx and Read the Docs.

I'm currently using NumPy style docstring, but Sphynx support few more styles if we decide that NumPy is too long.

The same repo is good for me.

I would say API with some docstring examples would be sufficient for a start. The actual usage flow could be demonstrated through some blog posts or hosted jupyter notebooks.

[AartGoossens]

Oh I like the idea of enriching a simple api documentation with blog posts and jupyter notebook! Let's try to go that route.