FreeOrion

Forums for the FreeOrion project
It is currently Thu Nov 23, 2017 5:21 am

All times are UTC




Post new topic Reply to topic  [ 10 posts ] 
Author Message
PostPosted: Thu Feb 25, 2016 12:35 pm 
Offline
Release Manager, Design
User avatar

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


Top
 Profile  
 
PostPosted: Thu Feb 25, 2016 4:13 pm 
Offline
Programmer

Joined: Sun Feb 14, 2016 12:08 am
Posts: 343
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.


Top
 Profile  
 
PostPosted: Thu Feb 25, 2016 6:18 pm 
Offline
Release Manager, Design
User avatar

Joined: Wed Nov 16, 2011 12:56 pm
Posts: 4243
Location: Sol III
dbenage-cx wrote:
Maybe I don't understand the issue, is Doxygen not suitable?
Don't know, never used it. Maybe?
Quote:
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).


Top
 Profile  
 
PostPosted: Thu Feb 25, 2016 8:12 pm 
Offline
Programmer

Joined: Sun Feb 14, 2016 12:08 am
Posts: 343
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.


Top
 Profile  
 
PostPosted: Thu Feb 25, 2016 8:15 pm 
Offline
Programmer
User avatar

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


Top
 Profile  
 
PostPosted: Thu Feb 25, 2016 8:21 pm 
Offline
Release Manager, Design
User avatar

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


Top
 Profile  
 
PostPosted: Thu Feb 25, 2016 8:36 pm 
Offline
Programmer
User avatar

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


Top
 Profile  
 
PostPosted: Fri Feb 26, 2016 5:20 pm 
Offline
AI Contributor
User avatar

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


Top
 Profile  
 
PostPosted: Sun Feb 28, 2016 11:09 am 
Offline
Release Manager, Design
User avatar

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


Top
 Profile  
 
PostPosted: Sun Feb 28, 2016 7:09 pm 
Offline
Programming, Design, Admin
User avatar

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


Top
 Profile  
 
Display posts from previous:  Sort by  
Post new topic Reply to topic  [ 10 posts ] 

All times are UTC


Who is online

Users browsing this forum: No registered users and 1 guest


You cannot post new topics in this forum
You cannot reply to topics in this forum
You cannot edit your posts in this forum
You cannot delete your posts in this forum
You cannot post attachments in this forum

Search for:
Jump to:  
cron
Powered by phpBB® Forum Software © phpBB Group