yade-dev team mailing list archive

[Václav Šmilauer <eudoxos@xxxxxxxx>]

> In that case, I suggest to put as much as possible (i.e. everything not 
> _really_ technical) on the wiki. Since harder updates (finding the 
> files, syntax, no live feedback) will sum up with lazyness to prevent 
> sphinx changes.

"For besides other considerations, everybody is more inclined to neglect
the duty which he expects another to fulfill; as in families many
attendants are often less useful than a few. Each citizen will have a
thousand sons who will not be his sons individually but anybody will be
equally the son of anybody, and will therefore be neglected by all
alike." (Aristotle, Politics II, 3)

I would prefere put everything into sphinx for that reason (so far, it
has not been the case that people edit wiki because it is easier; there
were almost no edits at all, excapt everybody his/her page of interest).
Sphinx has several benefits which the wiki doesn't, among which:

* live yade sessions (i.e. the output in Out [43]: is really generated
by yade as the documentation is processed, not copy&pasted, therefore
always up to date)

* xrefs to yade classes/functions

* sphinx docs are packaged and can be browsed offline
(file:///usr/share/doc/yade-0.50/html/index.html if you have lucid's
yade-0.50-doc installed)

* you can easily type math in those docs.

> Ok, why not. The only thing I'm wondering is if first-time visitors will 
> not loose themselves in reference manuals before checking the wiki.

That is just a matter of designing the title page clearly. Currently, it
is not very well structured, but there is nolimits to your fantasy in
this respect, it is a pure HTML (doc/sphinx/templates/index.html FYI). I
think newcomers don't care what is wiki and what is sphinx, but they
want to know what they want to know.

> (btw, I didn't find any wiki in your links, bad examples?).

from https://yade-dem.org/sphinx/ , second paragraph:
"Yade is located at www.yade-dem.org, which contains this documentation
and wiki." ("wiki" is a hyperlink)

Whatever are those nice ideas about documentation, someone has to
implement them.

Cheers, v.