Replace manually maintained Python interface API reference wiki pages

[Vezzra]

The topic was brought up in PR #495: the idea is to remove the currently manually maintained (and therefore usually out-of-date) API reference of the Python interface and replace it by reference documentation auto-generated from Python docstrings in the source code (e.g. using tools like Doxygen).

A forum thread has been opened to discuss this topic:
http://www.freeorion.org/forum/viewtopic.php?f=4&t=9968

I've opened this issue so we don't forget about it. Incorporating the information on the current wiki pages into Python docstrings is only one step, and already worked on, providing a location where to host the new auto-generated reference documentation and implementing a workflow to keep it up-to-date needs to be done before the current wiki pages can be removed.

[Cjkjvfnby]

I will soon push changes for generator (it is broken now).

I have experience with http://www.sphinx-doc.org/en/stable/

[Cjkjvfnby]

Here is documentation example generated with sphinx Cjkjvfnby#15
Both example and generation code.
To check it you need

• fetch branch
• open documentation/build/html/index.html

[Vezzra]

Will get back to this and check it out once I've a bit more extra time, I'm still swamped and can't keep up ATM, so have to prioritize.

[adrianbroher]

Committed build artifacts are a no go.

[Vezzra]

I don't think @Cjkjvfnby has intended this to be actually merged, just as a demonstration on how this Sphinx tool works and what kind of output it produces. He provided it as a PR for his own fork after all...

[Vezzra]

Question: Has this already been sufficiently addressed by what is in place already, or is work on that still ongoing?

[adrianbroher]

No, I haven't touched this topic yet. To my most recent knowledge the generation of the documentation requires a running FO instance, which is interactive. So there is no way to do this on the CI server yet.

[Vezzra]

Do component:infrastructure issues really need a milestone? They usually don't affect releases at all...

[adrianbroher]

You're right.

[hifron]

Committed build artifacts are a no go.

Now there a more possibilities for build artefacts that could been commited by bot, there are a lot of projects that do that(but maybe not in C++ area) that automatically upgrade dependency versions of libraries and pull request is created(by bot) and after some time when they are successfully tested(maybe approved, maybe not, it depends on configuration) they are automatically merged(or approval is not so tough like weekly builds created automatically from branch)...

This bot created commits may also be doable for things like translation, when there are tools which uses also approval by another qualified user to approve one translation and after some time these approved translation are made to pull request by bot and may be merged if testing is successful and maybe approved. (currently doing translation for not so used language for FO is overkill to do by one person and such tool also watch changes to translation)... Such tools for translation are used by a lot of opensource projects...

---

Python documentation should be made in source code, but also some info in user form should be appropriate for beginner trying to do something and maybe also more advanced user after some time may benefit from it when his IDE doesn't help him or has not currently opened it and try to so something like catching some great idea...

---

CI and GitHub bots are a lot of better that used to be and some things could do also some scripts and generators...

Github Actions now support Sphinx including ReadTheDocs or GitHub Pages(where could be also C++ docs, not only Python)...