Documentation

Feb 20, 2014 at 3:00 PM
Hallo !
I have seen the new site (http://nanapro.org/) and the new documentation by Jean-Baptiste.
They looks great !
Sometimes I do not receive notifications on news (I have to revise all my subscription options), and have not seen the post https://sourceforge.net/p/nanapro/blog/2013/12/nana-documentation-wants-your-help/ . So, I'm late...
Some time a year ago I printed the Nana docs to learn about it. This is a .docx file (now a .odt). And I wanted to talk about.
I can see different kind of docs and this is what I think about it:
The “official”: (author driven)
A general docs. Generated independent of the nana source code. It is somewhat stable and therefor approximately bind-ed to some nana version. It roughly correspond to what was at http://nanapro.sourceforge.net/help/index.htm (now not working – could it contain a link to a new site?). It is now http://nanapro.org/help/html/index.html and is wonderful. The sources are now accessible for everyone who want to collaborate directly on each page, or all together in https://nanapro.codeplex.com/SourceControl/network/forks/jbksql/nanadoc/latest . (It will be best to be set also into the nanapro::master... just to make me ease to fetch it and merge with my working code). I think, with some automation it could be possible to convert into a printable book.
This is “official” and the sources are controlled by the authors, while any collaborator can contribute. This is perfect.
The “detailed” and current reference: (code driven)
Automatically generated from the nana source code by Doxigen. Not binded to a version, but to the “current” branch each want to document. It is provided in form of comment in the code and a “few” additional .markdonw files, also in the source code tree. It is automatically generated and not so pretty and “theme-able” as the official. I have something , and I propose to incorporate to the nanapro::master branch too. It will be very nice too, to have a working version of this reference for nana::master somewhere installed. I see CodePlex have a tab Documentation, with seem to be a good place for that... but I'm not sure (it is automatic generated, so, DONT need a version-control on it!).
I think the best reference - documentation is a well written code, with a few comment. So, I encourage to write as few and as short comments as possible, and rely more on good names. For example, in function declaration always name each argument with a possible long and meaningful name.
A wiki: (community driven).
Some projects had a wiki, for example in sourceforge. I have no idea how difficult is to set -up one, and even not much experience using it. But I guess it is the easier way to contribute, even for “occasional” contributors with don’t want to fork the code of nana or the documentation, but simply correct some error or quickly add some ideas. Also is a good place for discussion. Originally completely filled from the others will sometime used to set back the others docs. It can be still be moderated by the author.
Thank for your patience !
(upps... I have made an error: the post went to the ISSUES. ... but ok, there is the atached docx...)
Editor
Feb 21, 2014 at 12:15 PM
Hey,

I work on the Sphinx port, the main goal was to put the current doc in a manageable format so
everyone can edit/fix it by a simple commit. I agree that the doc should be Author documented at first and up to date
before releasing something new.

Sphinx dosen't generate the doc by reading the source code (less comments in source code but more work to document)
I put a todo module in my Sphinx version (newer than the one at nanapro.org) and a contibute guidelines if someone
want to help me during the process.
Feb 28, 2014 at 12:00 PM
Edited Feb 28, 2014 at 12:09 PM
Hy !
I have been playing (learning) with Doxygen for two week now, and it is amazing!
For example, It is trivial to add a ToDo list or a list of examples, and they got cross-referenced with the whole documentation automatically! More than that, the C++ code of the examples is fully automatically scanned and anything possible is converted into a link to the reference-doc, and the example cross-referenced there ! With just a few not trivial examples almost all the classes got a reference to one or more examples ! That’s is why I have include some examples from the documentation. With a litter more time I will write my owns.
With this “todo” Jinhao could tell us directly from the source where he expect some help or simple which are the future direction to work.
I have also used my old docx to input text into “pages” with markdown format. It is also very simple to do. This info come from all over the web, all written by Jinhao. I organized it a litter and wanted to help improving the English, but It is also not my language (I use a kind of google-translated English).
I will contribute to the Sphinx documentation, but I think I better wait until Jinhao merge it into nanapro/master, because I normally do a big mess merging branches (also, I have no Phyton installed now :-( ). Until that I hope you can use the Doxygen docs (you can download/see it in myNana/Doxy_1 branch) to add/actualice information into the Sphinx documentation. Of course, I have also looked at the Sphinx documentation to add to the Doxygen docs.
Editor
Mar 3, 2014 at 4:00 PM
I think having both Doxygen and Sphinx makes just things more confusing.
Here we are doing 2 documentations... we better focus on one instead of working separately
for the same goal. Let's see what jinaho think about this
Mar 15, 2014 at 1:32 AM
Edited Mar 15, 2014 at 1:36 AM
Hi,
I understand your concern about effort duplication. But don’t worry, it is only apparent. I finished (2014.03.07, myNana/master) to port the information (basically just copy/paste) I collected from various cnjinhao sites in the doc I used to print and read, converting it into comments in the source code and some few markdonw docs. I also compiled and run most of the original examples. The goal of these work is very different from the “official” documentation. I use this automatic reference all the time, mostly as an alternative code navigator with for some proposes is superior to the IntelliSense of MSVS, and let me to investigate nana and experiment new ideas. But it lack the logical structure and consistence of a documentation useful to learn and understand Nana, and also to formalize it and use it more “conservative” in “production code”, and witch obviously is a lot more complicated to achieve.
Now, a litter about the commits... I'd suggest to keep both docs in the same sub directory “docs”, because they don’t interfere. Sphinx hat a sophisticate project “make”, and probably can be moved all around and function equally good. Bot the Doxygen projects are simpler and I will need to do some changes to merge it back and make it work. Also, it will be used to generate the docs of anyone’s branch, and I see litter point in having my username hard coded in the source tree. If we think this are only temporal versions, we can put it in “docs” and the final version in a more formal parallel directory “documentation”. More than that, we need the sub directory “examples” in the “demo” directory, with are programs tested to be compiled, that is – example source code, not only documentation. And finally, of course, the most important thing: a lot of comments in the nana source code have to be merged.