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: 4677
Joined: Wed Nov 16, 2011 12:56 pm
Location: Sol III

Python API reference documentation

#1 Post by Vezzra » Thu Feb 25, 2016 12:35 pm

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 » Thu Feb 25, 2016 4:13 pm

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: 4677
Joined: Wed Nov 16, 2011 12:56 pm
Location: Sol III

Re: Python API reference documentation

#3 Post by Vezzra » Thu Feb 25, 2016 6:18 pm

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 » Thu Feb 25, 2016 8:12 pm

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: 1072
Joined: Fri Mar 01, 2013 9:52 am
Location: Germany

Re: Python API reference documentation

#5 Post by adrian_broher » Thu Feb 25, 2016 8:15 pm

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: 4677
Joined: Wed Nov 16, 2011 12:56 pm
Location: Sol III

Re: Python API reference documentation

#6 Post by Vezzra » Thu Feb 25, 2016 8:21 pm

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: 1072
Joined: Fri Mar 01, 2013 9:52 am
Location: Germany

Re: Python API reference documentation

#7 Post by adrian_broher » Thu Feb 25, 2016 8:36 pm

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: 452
Joined: Tue Jun 24, 2014 9:55 pm

Re: Python API reference documentation

#8 Post by Cjkjvfnby » Fri Feb 26, 2016 5:20 pm

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: 4677
Joined: Wed Nov 16, 2011 12:56 pm
Location: Sol III

Re: Python API reference documentation

#9 Post by Vezzra » Sun Feb 28, 2016 11:09 am

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: 12284
Joined: Wed Oct 08, 2003 1:33 am
Location: Munich

Re: Python API reference documentation

#10 Post by Geoff the Medio » Sun Feb 28, 2016 7:09 pm

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.

Post Reply