A huge +1. Thanks for the effort and I hope you continue it! Documentation is one area where rsyslog is really lacking, imho. Or let me rephrase that: While there is a quite a bit of documentation, it's inconsistent and undiscoverable. With all the features (and this list is growing) it's harder and harder to find help on a given topic.
I can't really comment on spinx as a technology (never used it myself) but the generated (html) output looks nice. IIRC there were attempts in the past to migrate the documentation to docbook, but they failed ultimately. Not quite sure why. I guess it simply needed someone to follow through with this. As for spinx: Does it provide mechanisms to integrate translations (should there ever be one)? 2013/5/10 Jerome Renard <[email protected]>: > Hello, > > A couple of days ago, Rainer ask me to update the doc to include the > new configuration flags I added for omelasticsearch. > But then I realized I had to update a raw HTML file and I was > wondering if there was a simpler way to contribute to the > documentation. > > So I made an experiment with Sphinx [1] and converted a couple of > existing documentation pages to ReST which is the format Sphinx > supports. > Doing the conversion was quite easy, especially with the help of PanDoc [2]. > > You can have a look at what some documentation files look like with > ReST in Sphinx here: > - https://github.com/jeromer/rsyslog-alternativedoc > > If you want to build the documentation, just install Sphinx and run make html. > If you are lazy you can still have a look at the attached tarball [3] > which contains the built documentation. > Just open build/html/index.html (you can even test the search page if you > want). > > advantages of using Sphinx are: > - simple to use > - simple to build > - proven technology (the python documentation - and many others - are > powered by Sphinx) > - can be "themed" so the UI can be consistent with the Rsyslog website > - easy to deploy, simple HTML files > > The only drawback I see is that the documentation needs to be > converted, but this is far for being hard. > > I would like to get your feedback about this experiment. > Do you think migrating the actual doc to a Sphinx based doc is worth it ? > I believe this would make it easier to use the documentation and make > rsyslog a bit easier to use for beginners. > We could even merge the wiki and the documentation in order to get one > source of documentation. > > Have a nice day :) > > 1. http://sphinx-doc.org/ > 2. http://johnmacfarlane.net/pandoc/ > 3. build.tar.gz > > -- > Jérôme > > _______________________________________________ > rsyslog mailing list > http://lists.adiscon.net/mailman/listinfo/rsyslog > http://www.rsyslog.com/professional-services/ > What's up with rsyslog? Follow https://twitter.com/rgerhards > NOTE WELL: This is a PUBLIC mailing list, posts are ARCHIVED by a myriad of > sites beyond our control. PLEASE UNSUBSCRIBE and DO NOT POST if you DON'T > LIKE THAT. -- Why is it that all of the instruments seeking intelligent life in the universe are pointed away from Earth? _______________________________________________ rsyslog mailing list http://lists.adiscon.net/mailman/listinfo/rsyslog http://www.rsyslog.com/professional-services/ What's up with rsyslog? Follow https://twitter.com/rgerhards NOTE WELL: This is a PUBLIC mailing list, posts are ARCHIVED by a myriad of sites beyond our control. PLEASE UNSUBSCRIBE and DO NOT POST if you DON'T LIKE THAT.
