Python API reference documentation

Discussion about the project in general, organization, website, or any other details that aren't directly about the game.
Post Reply
Message
Author
User avatar
Vezzra
Release Manager, Design
Posts: 6095
Joined: Wed Nov 16, 2011 12:56 pm
Location: Sol III

Python API reference documentation

#1 Post by Vezzra »

On github a discussion started on how and where to provide the reference documentation for the Python API reference (see here). As discussions like that acutally belong here on the forum, I'll provide the relevant statements, and ask that everyone continues the discussion here:
Vezzra wrote:
Cjkjvfnby wrote:Its bad to have code and docs in different places.
Why? AFAIK that's actually "common standard", reference manuals are exactly that - a documentation outside the code. And while I'm very much in favor of adding these docstrings to the Python interface, I certainly don't want to remove the Python API reference wiki page (without a proper replacement, that is).

That said, I do see the hassles with trying to maintain two sets of documentation (the one in the source code and the one on the wiki page). AFAIK there are tools which can compile reference docs out of the docstrings in Python code, if we can somehow incorporate such autogenerated docs into our wiki page, or at least put them somewhere where we can link to from the wiki page, that would be fine too.

Just don't provide the reference documentation for the Python API by Python docstrings only. I'm a person who prefers to have reference docs open in a separate (browser) window (or even printed out on paper!), not buried in some source code or only accessible by pop-ups in my IDE. I'm sure there are others like me out there. :wink:
adrain_broher wrote:
Vezzra wrote:Why? AFAIK that's actually "common standard", reference manuals are exactly that - a documentation outside the code. And while I'm very much in favor of adding these docstrings to the Python interface, I certainly don't want to remove the Python API reference wiki page (without a proper replacement, that is).
I don't know what you're meaning with reference manuals, but most projects I use and maintain create their API and high level documentation from in code documentation. If it is about publishing the results on a web page/wiki it should be no issue in adding a make target for that.
Cjkjvfnby wrote:Documentation support. You will not update documentation on wiki after API changes: "This page was last modified on 10 April 2012, at 16:55."

I don't know how to put generated docs to wiki, but I know how to make docs page on https://readthedocs.org/. If you want I can do some examples.
Vezzra wrote:
adrian_broher wrote:I don't know what you're meaning with reference manuals
E.g. this: https://docs.python.org/2.7/library/index.html
adrian_broher wrote:most projects I use and maintain create their API and high level documentation from in code documentation. If it is about publishing the results on a web page/wiki it should be no issue in adding a make target for that.
This. What I definitely do not want is to just move all the API reference documentation into docstrings, which after all get specified and passed to Python in C++ code. Without further processing they are not of much use there, and most certainly no adequate replacement for the wiki page.

But if we can devise a workflow by which we can generate reference documentation out of this in-code documentation, that's certainly fine, and far better than the current situation.

If you know a way how to generate wiki page content (which we could simply paste into our wiki) from these Python docstrings, that would be an solution I'd prefer.
Vezzra wrote:
Cjkjvfnby wrote:Documentation support. You will not update documentation on wiki after API changes
Of course that's a big problem, I won't contest that. But, as I said in my reply to @adrianbroher above, unless we can generate documentation we can provide elsewhere out of these docstrings, still better than having only the docstrings.
Cjkjvfnby wrote:I don't know how to put generated docs to wiki, but I know how to make docs page on https://readthedocs.org/.
That could work too, although I'd prefer something we could paste into our wiki pages. However, if we can't do that, readthedocs.org is probably worth a try.

dbenage-cx
Programmer
Posts: 389
Joined: Sun Feb 14, 2016 12:08 am

Re: Python API reference documentation

#2 Post by dbenage-cx »

Maybe I don't understand the issue, is Doxygen not suitable?

If it absolutely needs to be in a wiki page, there is https://github.com/Coburn37/DoxygenMediawikiBot
Though I dont know if the setup would be worthwhile compared to just linking the doxygen output.
Any content posted should be considered licensed GNU GPL 2.0 and/or CC-BY-SA 3.0 as appropriate.

User avatar
Vezzra
Release Manager, Design
Posts: 6095
Joined: Wed Nov 16, 2011 12:56 pm
Location: Sol III

Re: Python API reference documentation

#3 Post by Vezzra »

dbenage-cx wrote:Maybe I don't understand the issue, is Doxygen not suitable?
Don't know, never used it. Maybe?
If it absolutely needs to be in a wiki page, there is https://github.com/Coburn37/DoxygenMediawikiBot
Though I dont know if the setup would be worthwhile compared to just linking the doxygen output.
Well, it doesn't absolutely need to be a wiki page, of course we can just link from the wiki to the doxygen output - which needs to be hosted somewhere however. And this is something I'd rather avoid, scattering our project over even more sites. We already have the wiki (the official homepage), the forums, github (the repository) and sourceforge (where we host the installer packages for Windows and OSX for download).

A site like readthedocs.org would add yet another one. So, if there is a (not too complicated) way to produce an output that can be hosted directly on the wiki, that would be preferable (IMO).

dbenage-cx
Programmer
Posts: 389
Joined: Sun Feb 14, 2016 12:08 am

Re: Python API reference documentation

#4 Post by dbenage-cx »

Brought up Doxygen since it is already setup for GG

https://github.com/freeorion/freeorion/ ... oxyfile.in

re: hosting, link to github/freeorion/freeorion/doc/index.html and then only update on release builds?
Unless that is against some TOS or bandwidth considerations.
Any content posted should be considered licensed GNU GPL 2.0 and/or CC-BY-SA 3.0 as appropriate.

User avatar
adrian_broher
Programmer
Posts: 1156
Joined: Fri Mar 01, 2013 9:52 am
Location: Germany

Re: Python API reference documentation

#5 Post by adrian_broher »

dbenage-cx wrote:re: hosting, link to github/freeorion/freeorion/doc/index.html and then only update on release builds?
Unless that is against some TOS or bandwidth considerations.
NO!

Build artifacts don't belong into a source repository.
Resident code gremlin
Attached patches are released under GPL 2.0 or later.
Git author: Marcel Metz

User avatar
Vezzra
Release Manager, Design
Posts: 6095
Joined: Wed Nov 16, 2011 12:56 pm
Location: Sol III

Re: Python API reference documentation

#6 Post by Vezzra »

adrian_broher wrote:Build artifacts don't belong into a source repository.
The solution for that would be easy: provide a repo "freeorion-docs" and store all the auto-generated reference documentation there.

User avatar
adrian_broher
Programmer
Posts: 1156
Joined: Fri Mar 01, 2013 9:52 am
Location: Germany

Re: Python API reference documentation

#7 Post by adrian_broher »

Vezzra wrote:
adrian_broher wrote:Build artifacts don't belong into a source repository.
The solution for that would be easy: provide a repo "freeorion-docs" and store all the auto-generated reference documentation there.
Better use the wiki repository then, it logical closer to the FreeOrion code.

https://help.github.com/articles/adding ... s-locally/
Resident code gremlin
Attached patches are released under GPL 2.0 or later.
Git author: Marcel Metz

User avatar
Cjkjvfnby
AI Contributor
Posts: 539
Joined: Tue Jun 24, 2014 9:55 pm

Re: Python API reference documentation

#8 Post by Cjkjvfnby »

adrian_broher wrote:
Vezzra wrote:
adrian_broher wrote:Build artifacts don't belong into a source repository.
The solution for that would be easy: provide a repo "freeorion-docs" and store all the auto-generated reference documentation there.
Better use the wiki repository then, it logical closer to the FreeOrion code.

https://help.github.com/articles/adding ... s-locally/
I like idea with separate repo.

I like https://readthedocs.org/ it can fetch and build docs from github. IMHO It can totally replace wiki.
If I provided any code, scripts or other content here, it's released under GPL 2.0 and CC-BY-SA 3.0

User avatar
Vezzra
Release Manager, Design
Posts: 6095
Joined: Wed Nov 16, 2011 12:56 pm
Location: Sol III

Re: Python API reference documentation

#9 Post by Vezzra »

Cjkjvfnby wrote:I like https://readthedocs.org/ it can fetch and build docs from github.
That's certainly a very appealing feature, but still, it would be yet another separate site where we host FO stuff, and that's why I'm reluctant to use it.
IMHO It can totally replace wiki.
Assuming you don't mean the entire FO wiki (which is actually the official homepage of the project), but only the wiki page about the Python AI interface API reference - not so sure about the "totally". There are a few introductory paragraphs which are important and probably wouldn't be part of an auto-generated reference, but still need to be kept.

Finding a way to put all of that together so we end up with reference pages that are both easy to maintain and comfortable to use will be the challenge here.

User avatar
Geoff the Medio
Programming, Design, Admin
Posts: 13587
Joined: Wed Oct 08, 2003 1:33 am
Location: Munich

Re: Python API reference documentation

#10 Post by Geoff the Medio »

Vezzra wrote:There are a few introductory paragraphs which are important and probably wouldn't be part of an auto-generated reference, but still need to be kept.
Probably there should be more than one page with the API info in it, rather than one huge page with everything. The intro page would be separate from all the pages that describe various API features.

hifron
Krill Swarm
Posts: 11
Joined: Sun Jul 03, 2022 8:35 pm

Re: Python API reference documentation

#11 Post by hifron »

old Issue
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, but maybe also for Wiki there is some solution)...

Ophiuchus
Programmer
Posts: 3433
Joined: Tue Sep 30, 2014 10:01 am
Location: Wall IV

Re: Python API reference documentation

#12 Post by Ophiuchus »

hifron wrote: Sat Aug 06, 2022 1:51 pm 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, but maybe also for Wiki there is some solution)...
i find sphinx an acceptable solution for tech documentation. We used it in company when we needed also to generate printable documentation - it was the most fitting solution for us. As nobody stated the obvious - it can also generate html, so we could host that on our site.

Having documentation in the source repository instead of the wiki also helps with versioning.

Main downside for wiki is that documentation changes become a PR / need to be looked at by somebody who has a right to merge.

dunno about github - probably they can give merge rights for PR which only touch certain directories?
Any code or patches in anything posted here is released under the CC and GPL licences in use for the FO project.

Look, ma... four combat bouts!

hifron
Krill Swarm
Posts: 11
Joined: Sun Jul 03, 2022 8:35 pm

Re: Python API reference documentation

#13 Post by hifron »

Ophiuchus wrote: Fri Aug 12, 2022 10:01 am dunno about github - probably they can give merge rights for PR which only touch certain directories?
There is page https://freeorion.github.io/ which could somehow be made... More on pages by Github on https://pages.github.com/ or https://docs.github.com/en/pages/gettin ... pages-site

When clicking(adjusted for FO, need admin rights(could be seen on your fork page)) https://github.com/freeorion/freeorion/settings/pages there are settings which could be also deployed from Github branch or by Github Action(like with Sphinx bot, but FIRST maybe for easy setup from branch is better). GitHub Marketplace Apps on Sphinx https://github.com/marketplace?query=sphinx+, but offline local Sphinx to test and then commit to branch...

hifron
Krill Swarm
Posts: 11
Joined: Sun Jul 03, 2022 8:35 pm

Re: Python API reference documentation

#14 Post by hifron »

There is also option to use snap packages by Michael Sweet(known for openprinting.org and CUPS by Apple) like codecov, but don't know(and from man pages to something is also possible, also like publish man pages to ReadTheDocs by GH action).

Post Reply