Social Media

  • Facebook
  • Google+

Latest Posts

Topic: Documentation rework

kaputtnik
Avatar
Joined: 2013-02-18, 20:48
Posts: 1480
Ranking
One Elder of Players
Location: Germany
Posted at: 2018-05-17, 18:22

The current documentation is made with an old django-app called django-sphinx. This application isn't maintained anymore and makes it impossible to update Django itself in the future. To get rid of this application there is an attempt to build the documentation directly as html files and serve those.

You can find a test setup at http://alpha.widelands.org/documentation/

Any remarks or suggestions?


Top Quote
ypopezios
Avatar
Joined: 2018-04-20, 00:22
Posts: 220
Ranking
Widelands-Forum-Junkie
Posted at: 2018-05-17, 18:33

Why not use the wiki instead?


Top Quote
kaputtnik
Avatar
Joined: 2013-02-18, 20:48
Posts: 1480
Ranking
One Elder of Players
Location: Germany
Posted at: 2018-05-17, 20:20

Sidenote: If we talk about 'documentation', the currently documentation is mainly about LUA scripting. So it is useful for people who wants to create an own scenario.

ypopezios wrote:

Why not use the wiki instead?

Using the Wiki would cause additional work. The source code documentation is best done in the source code itself. So a new developer can read it directly when he wants to edit the code. If a developer should do the documentation in two places (source code and Wiki), it causes additional work wich is error-prone and time consuming.


Top Quote
einstein13
Avatar
Joined: 2013-07-29, 00:01
Posts: 998
Ranking
One Elder of Players
Location: Poland
Posted at: 2018-05-17, 21:03

Ohh... You mean documentation = part of our site that is generated out of Widelands code itself?

I don't know almost anything about that, so I will not say anything against what you develop. You are my hero here! face-smile.png


einstein13
calculations & maps packages: http://wuatek.no-ip.org/~rak/widelands/

Top Quote
GunChleoc
Avatar
Joined: 2013-10-07, 15:56
Posts: 2578
Ranking
One Elder of Players
Location: RenderedRect
Posted at: 2018-05-22, 08:25

Looking good face-smile.png

Just 1 nit: I find the menu text hard to read in the left sidebar - use black text? Or the same style as on the top.

There is one more reason not to use the wiki for this: When changing the code, a developer will see that there is some documentation that goes with it. If it's in the wiki, developers will forget to update the documentation when making changes, because it's out of sight. We would end up with horribly outdated documentation.


Busy indexing nil values

Top Quote
kaputtnik
Avatar
Joined: 2013-02-18, 20:48
Posts: 1480
Ranking
One Elder of Players
Location: Germany
Posted at: 2018-05-23, 08:42

GunChleoc wrote:

Just 1 nit: I find the menu text hard to read in the left sidebar - use black text? Or the same style as on the top.

I will give the text a real dark green then. If this isn't satisfying, we can change it also later.

May i find time this evening to get the new documentation on the productive site.


Top Quote
kaputtnik
Avatar
Joined: 2013-02-18, 20:48
Posts: 1480
Ranking
One Elder of Players
Location: Germany
Posted at: 2018-05-27, 11:42

The new documenation is online now. It may take a short time to load the css the first time you call it.

Hopefully you like it face-smile.png


Top Quote
GunChleoc
Avatar
Joined: 2013-10-07, 15:56
Posts: 2578
Ranking
One Elder of Players
Location: RenderedRect
Posted at: 2018-05-30, 15:11

Thanks!


Busy indexing nil values

Top Quote