yade-dev team mailing list archive

[Bruno Chareyre <bruno.chareyre@xxxxxxxxxxx>]

> > - Python pages. They were very usefull for me. They are written in 
> > beginner-friendly style, and I also tend to see them also as part of the 
> > overview : it gives the taste of how Yade works before diving in a 
> > technical documentation. I would keep them in the wiki, but maybe it 
> > will be considered a duplicate of sphinx?
> >     
> There is already the introductory chapter in sphinx,
> https://yade-dem.org/sphinx/introduction.html . Perhaps it could contain
> some example of a simple simulation as whole, something like
> simple-scene perhaps, or at least a link to it.
>
>   
Yes, we can crosslink wiki->sphinx and sphinx->wiki in many places.
Simple-scene.py/.cpp are good pages that we should not loose (but they 
need update).
They can be in sphinx with links from wiki, or the opposite, for me it 
makes no difference.
The page https://yade-dem.org/sphinx/introduction.html is not something 
that the average human will read without a good reason, simple-scene is 
more an "overview" thing. By the way, the two figures in 
introduction.html don't display correctly for me.

> I think it does not change _that_ often, and it would make sense to make
> it a part of sphinx. Sphinx docs are in trunk and people changing stuff
> should update it themselves. I definitely will _not_ conpoensate
> lazyness of other in this respect.
>   
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.
> > I'd like a few good images in this first page too, any suggestion?
> >     
>
> I would suggest to make the sphinx home https://yade-dem.org/sphinx/ as
> the main page for http://www.yade-dem.org, and only reference wiki from
> there. We wouldn't be the first ones to do that (e.g.
> http://docs.python.org/ or http://matplotlib.sourceforge.net/)
>
>   
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.
It is less risky the other way, with people getting an overview from 
wiki, then moving to sphinx if they really want to read the 
documentation. If we do that, we need a very visible link at the top of 
the page, something like "YADE Project General Introduction (WIKI)" 
(btw, I didn't find any wiki in your links, bad examples?).

Bruno