Auto-generate Doxygen-generated documentation

[Nicolai Hähnle]

We have the capability to generate source code documentation using Doxygen. While everybody is free to generate it his or herself, it would be really nice to have this available automatically generated via the website from trunk, similarly to the Lua documentation.

[Shevonar (shevonar)]

I also think that having the documentation online is easier than everyone building it for himself. I will see if I can figure out a good way to auto-generate it on a server and then ask Sirver to do so on the Widelands server.

[kaputtnik (franku)]

The lua documentation has a big shortcoming: There is currently no possibility for searching and the related django-app isn't maintained anymore, a search wouldn't be implemented.

Since both, doxygen and sphinx can make full featured html files, why do we not serve just the produced html?

Or/and provide the documentations as zip files for download? Build them daily (or once a month) on the server and provide a download link. Some starter pages, which will likely not change that often, can be included in the wiki.

BTW: Building the doxygen generated html results in lot of warnings and undocumented parameters e.g.

src/economy/input_queue.h:175: warning: argument 'fr' of command @param is not found in the argument list of Widelands::InputQueue::read(FileRead &f, Game &g, MapObjectLoader &mol)

src/economy/economy.h:205: warning: unable to resolve reference to `Cmd_Call_Economy_Balance' for \ref command

I looked into one and it seems those warnings are just there because a change of a variable name was not reflected for the documentation part. Or are forgotten to remove during restructuring? Anyway the produced documentation is working. No idea if it is also valid :-D

[GunChleoc (gunchleoc)]

Isn't the Sphinx documentation already available as HTML? It's on the website after all, so I don't understand what you mean here.

I have never generated the Doxygen documentation, because I just use my IDE to read the comments and header files. Fixing the errors & warnings is desirable though.

[kaputtnik (franku)]

The sphinx documentation is produced as json files. django_sphinx reads them out and passes them through the django template system.

The documentation on the website lacks searching: https://wl.widelands.org/docs/wl/search/
Say some one looks into a campaign and wants to know the documentation of a function/property. Without the possibility to search for it he may get lost and looses interest. At least for me searching the documentation is very helpful and i am happy to have it as html on my disk, where i can search.

I have no idea though, how to provide pure html from the server. I think there has to be some modifications to nginx then.

[GunChleoc (gunchleoc)]

Calling make html instead of make json should do it, along with the following configuration:

https://nginx.org/en/docs/beginners_guide.html#static

[kaputtnik (franku)]

Thanks for looking at the docs :-)

If we want to use the static html, i thought of making it a bit looking like the widelands webpage.

First screenshot.

[kaputtnik (franku)]

As ever, the devil is in the details...

First of all i have tried to make a python script for the website which lives in the directory _ops. Calling this script fails some how. It looks like python doesn't allow access to folders or files beginning with an underscore...

Then i tried to put my script in the base directory of the website, then it works, but calling extract_rst.py through execfile() do not work. I get an error:

curdir = p.abspath(p.dirname(__file__))
     86 source_dir = p.join(curdir, 'source')
     87 while not (p.exists(p.join(curdir, 'data/tribes')) and p.exists(p.join(curdir, 'data/world'))):

NameError: global name 'p' is not defined

I do not understand that. Maybe the double use of 'import os' is the culprit?

[GunChleoc (gunchleoc)]

I think that "import os.path as p" is just there because somebody didn't like typing. How about removing that line and calling os.path explicitly? I'd find that more readable anyway.

[kaputtnik (franku)]

Yes, i will change the "import os.path as p".

Regarding my previous post: I just thought too complicated :-) I have a working solution now at home but need some investigation on the server.

[kaputtnik (franku)]

Just found that the RST from src/scripting/lua_path.cc wasn't included in the documentation, so i added it to the widelands branch. This may need some tweaking from a real developer...

[GunChleoc (gunchleoc)]

The table of contents in the screenshot looks good BTW - it is sorely needed.

I have been thinking, we could do both Doxygen and RTS - RTS for Lua scripting folks, and C++ for engine developers. This way, we can insulate Lua developers from the nitty-gritty of the engine, and also have 2 different documentation versions for the same function if needed.

I have never build the Doxygen documentation personally though, because I just use my IDE to navigate the code. So, I have no idea what state it's in - we certainly don't keep to the standard.

[kaputtnik (franku)]

I do also think that splitting C++ from Lua is a good thing. We could have two links then, one for scripting and one for C++.

What about the "Developers Documentation" (https://wl.widelands.org/docs/wl/development/)? I guess this is old stuff and could be removed? The thing with std::set<SomePointer*> could be added to the c++ documentation then.

Building the doxygen documentation takes currently very long and takes much processor time (this week it made my computer crash because the processors heat reaches maximum of 70°). This is because the setting in the doxyfile is set to create html imagemaps for the class dependencies (up to 1000 nodes) with graphviz. The imagemaps a partly really big... nice to watch, but could at least be stripped down so they are less processor consuming.

For now i would say lets make the LUA documentation standalone and add a C++ documentation later on.

Maybe next week i make a testrun on the alpha site and make a call for testing.

[GunChleoc (gunchleoc)]

Let's leave the developers documentation in for now, until we have a new place to put it.

The Doxygen runtime sounds bad - we definitely need to do something about that.

[GunChleoc (gunchleoc)]

Issue moved to https://github.com/widelands/widelands-website/issues/204

[GunChleoc (gunchleoc)]

Migrated to https://github.com/widelands/widelands/issues/1914