Deciding on a documentation workflow

[git-staus]

As discussed under #9, more closely integrating and structuring the existing documentation with the mocket source code would be desirable. I am raising this issue or discussing how to actually do this.

Current documentation

At the time of writing, the README describes all existing mocket documentation. The outlinks in the section "How to use it" are all still relevant despite their age. Many examples are also given in the section "Example of how to mock an HTTP[S] call" and onwards.

Currently the codebase does not seem to make use of docstrings.

Requirements for the new documentation

Here are some concerns I came up with that might need a second opinion:

1. A separate docs/ directory with plain text will get out of sync with the code and is unmaintainable, so a system to automatically derive documentation from docstrings etc. in the code and test it and so forth seems worthwhile.

2. The project already uses reStrucuturedText (RST) markup so it makes sense to use a system that uses that as well (instead of e.g. MarkDown).

3. It should have an option to collect all in-code documentation into some kind of (HTML?) document for referencing à la Rust's cargo. Hosting such documentation online would be a second step that would be useful for raising the visibility of mocket, but that depends on the resources available to the mocket maintainers and is outside the scope of this issue. Just giving downstream users the options to compile such a document (locally) is already valuable.

4. Despite the first requirement, we already have a few general examples of mocket usage (instead of demonstration of a specific class or function). A documentation system that also supports some kind of examples/ directory that is checked / compiled as part of the documentation workflow would be nice.

On the topic of the above requirement, this webpage sketches out the different types and purposes of Python documentation and might be relevant on deciding how to focus documentation efforts.

Frameworks to choose from

The first search engine hit already gives quite an impressive list (see there). Here are some notes on only some of the systems listed:

1. Sphinx already uses RST.

2. Read The Docs seems the most prevalent in the Python ecosystem. I believe it is also linked to the webhosting service they seem to provide.

3. doctest Already in the standard library, but I don't believe it does more than validate code examples within docstrings. Not sure if it supports RST.

4. Doxygen It seems a bit silly to use this language-agnostic tool for a Python project given all the other Python-specific projects. I am pretty sure it does not support RST. I also do not like it personally.

Does anybody have recommendations / previous experience? Do we need a longer list of options to choose from?

Next steps

Once there some kind of consensus on what to use, I suggest that the first step would be to (raise a new issue to) put the relevant parts of all the current documentation under version control in this repository and integrate it in the chosen system and work from there.

There is also the machine-generated documentation that seems pretty extensive but which I personally would not feel comfortable providing for downstream users without people with experience with the code base validating and committing each of its claims (but maybe I am just not following along with the times).

As discussed under the aforementioned #9, further prose documentation on each item in the API interface can be based on the extensive test suite.

[mindflayer]

There's the option to go for GitHub Pages too.

[mindflayer]

On the topic of the above requirement, this webpage sketches out the different types and purposes of Python documentation and might be relevant on deciding how to focus documentation efforts.

This is really interesting. As a new Mocket user, what do you need the most for being successful at integrating Mocket into your test suite?
Following what you shared from Divio, do we need more tutorials, how-to guides, technical reference or explanation, in your opinion?

[git-staus]

Since I actually still haven't started writing the tests that initially led me to mocket, I will probably have a better clue about how to answer that question soon! Do any other users reading this have insights here?

[mindflayer]

I've just discovered this project, it looks quite interesting.
Would you like to give it a try?

[git-staus]

Thanks for helping move this forwards! I have been a bit overwhelmed with all the options out there, but this looks really nice, and very mature too.

However, this uses MarkDown instead of reStructuredText like our README does. Is that OK with the maintainers? pdoc even recommend Sphinx for "substantially more complex documentation needs". Does something with meta-tests that monkey-patches the Python core libraries like mocket fit that criterion?

I am happy to try my hand at a PR for any framework of your choosing. Feel free to close this issue and assign me to a new one if there is a clear winner.

[mindflayer]

Is that OK with the maintainers?

I think we should forget about the README for now, and focus on the current goal, which is the lack of proper documentation. With a documentation in place, we'll consider reducing or changing the scope of the README.

[git-staus]

In that case I choose to go with pdoc for my PR. I deem that to be the route of least resistance because I personally find its documentation more accessible than Sphinx's and because I know MarkDown better than RST.