Based on some of the previous comments/concerns over Nim documentation, this seems like it might address some of the issues:
http://stackoverflow.com/documentation/nim/commit
Upvote if you're interested.
There is work being done right now to create much better documentation for Nim. The basics are done and we figure out some of the details and work on the implementation.
This will be based on the current way on how Nim documentation is written. Inside the Code, with optional includes of additional rst files. One goal is to have a central place for all Nim documentation and a way for every third party Tool to easily get access to it too. Maybe even creating an API eventually.
Please stay tuned and in the meantime fix and extend the documentation in your modules and the compiler!
Well. It could be as simple as creating PR where multiple people working in collaboration to add to the documentation. There is no need to extract them from the sources and re-inject them again.
For some key modules there also could be some example.rst files which get included with the module and have examples (and linking) to the module itself.
I don't want to announce a time frame right now, because I also have a day job :)
The idea is pretty simple: We collect all the docs from all the modules which are in nimble automatically and add the docs of the compiler and the manual itself.
Those get indexed by the Nim compilers own doctools. This generates "namespaced" repositorys of documentation per module. We store the data in json (jsondoc2) which then is the basis for a SPA style documentation site.
This site will contain documentation for all of Nim and can be cross referenced over module borders. It also will offer smart search features over all indexed modules. In addition we will construct static indexing sites with all of the same information linked in conventional manner which will be indexed by search engines.
The site may very well get enhanced eventually with comments but that is not planed from the beginning. This would need moderation and could be target for spam and stuff. I simply don't want to put that burden upfront.
It may also function as online search for nimble packages as all the information would be available there already.
I am in the proof of concept phase and later on we will move to a real database backend. I am not sure if that servers code will be public domain. At least it will be available for free for Araq. He and me work in the same company and we can use our framework for that, which also means that we may host it. My Company agreed on investing into Nim some time ago and I guess that may be the easiest way to have something really useful for the community.
The basics which are needed for that got included to the compiler in the last days. One can now generate all the docs for a project by one command (nim doc2 --project index.nim, where index.nim is a nim file including everything which belongs to the module being documented).
That is the reason why I would love that people start to add documentation in the "Nim way", because it will be of use for everyone in the near future.
@OderWat Any updates on this?
I've noticed that the docgen tool has very limited support of field lists. It would be good to be able to add parameter descriptions via field list fields but at the moment this doesn't seem to work.
Also if there was support for multiline comments for documentation rather than having to double hash all documentation comments this would make writing documentation easier and make it more readable. This would potentially make people happier and more likely to write documentation if its easier.
I agree, we need to do a better job of getting feedback from the readers of our documentation. I bet we could create a simple web service for that.
Easily editing documentation is more difficult, but something which would be nice too. We can definitely improve our documentation a lot.
For the upcoming 0.15.0 I have generated documentation here (still subject to change and yes I know the version says 0.14.3):
http://nim-lang.org/0.15.0/lib.html
http://nim-lang.org/0.15.0/asynchttpserver.html
New features:
Please give it a try!
These features are implemented in Nim with the JS backend, so if you like to improve the search algorithm etc, edit tools/dochack/dochack.nim and start creating pull requests! :-)