Hi Adam, thank you very much for all the references, it's definitely interesting. OrientDB has always been a community-driven project, so any contribution is welcome. I've never used Sphinx personally, but it seems to be very promising, what are the needed steps to port our docs in there? Are there any changes to be done in the docs? OrientDB documentation is hosted here https://github.com/orientechnologies/orientdb-docs you can provide pull requests if needed. Do you think you can help on this?
Thanks a lot Luigi 2015-08-07 12:14 GMT+02:00 Adam Hunt <[email protected]>: > I've been experimenting with OrientDB recently and as one would expect > reading the documentation. In general I'd say that the quality of the > documentation is of a fairly high quality, especially for such a young > project. As I've been experimenting with and learning more about OrientDB I > thought that I might try to contribute in whatever limited way possible. > Seeing as I find myself digging through the documentation on a fairly > regular basis I thought that editing and expanding those docs might be a > good way to contribute. > > I feel that my *not* being an OrientDB engineer could be helpful when it > comes to documentation as I'm not so familiar with the topics at hand that > I assume the reader is already familiar with the underlying subject matter. > Also, I am a native English speaker (unfortunately, English is the only > spoken language I'm familiar with) and that seems to be the language that > Orient is targeting initially. > > While the current GitBook[0 <https://www.gitbook.com/>] based > documentation is reasonably effective and attractive I find myself > wondering if a tool such as Sphinx[1 <http://sphinx-doc.org/>] and > potentially by extension Read the Docs[2 <https://readthedocs.org/>] > which is based on Sphinx might be a better way forward. Sphinx is capable > of consuming and rendering the current GitHub flavor of Markdown[3 > <https://help.github.com/articles/github-flavored-markdown/>] based docs > that OrientDB's documentation is written in as well as the arguably more > rich reStructuredText[4 <http://docutils.sourceforge.net/rst.html>]. > Beyond markup, Sphinx is also capable of integrating with the JavaDoc[5 > <http://www.oracle.com/technetwork/java/javase/documentation/index-jsp-135444.html>] > based documentation that OrientDB already utilizes[6 > <http://orientdb.com/javadoc/latest/>] via the javasphinx[7 > <https://bronto.github.io/javasphinx/>] extension. Sphinx is also fully > internationalizable[8 <http://sphinx-doc.org/latest/intl.html>] such that > while English may be the initial language any other language could be added > as skilled translators become available. Aside from online HTML > documentation, Sphinx supports output to various other formats including > ePub (ebooks), Texinfo (Docbook and DVI), man pages, Microsoft Windows help > files, plain text, and likely others. > > Would porting the OrientDB's existing documentation to Sphinx or some > other documentation generator be something that Orient Technologies and the > community would be interested in? > > Thank you for your time, > > Adam Hunt > > > > [0] https://www.gitbook.com/ > [1] http://sphinx-doc.org/ > [2] https://readthedocs.org/ > [3] https://help.github.com/articles/github-flavored-markdown/ > [4] http://docutils.sourceforge.net/rst.html > [5] > http://www.oracle.com/technetwork/java/javase/documentation/index-jsp-135444.html > [6] http://orientdb.com/javadoc/latest/ > [7] https://bronto.github.io/javasphinx/ > [8] http://sphinx-doc.org/latest/intl.html > > -- > > --- > You received this message because you are subscribed to the Google Groups > "OrientDB" group. > To unsubscribe from this group and stop receiving emails from it, send an > email to [email protected]. > For more options, visit https://groups.google.com/d/optout. > -- --- You received this message because you are subscribed to the Google Groups "OrientDB" group. To unsubscribe from this group and stop receiving emails from it, send an email to [email protected]. For more options, visit https://groups.google.com/d/optout.
