Re: [sphinx-dev] Re: autodoc for Java source?
-BEGIN PGP SIGNED MESSAGE- Hash: SHA1 Am 27.02.2010 01:42, schrieb Roger Binns: Chris Collins wrote: Good idea. In case you're not familiar, Java has an automatic documentation feature called JavaDoc. I used Java from around its 1.0 days and consequently am very familiar with Javadoc. It was the first time a mainstream language had a single syntax and convention for doing doc with source. (Yes other languages had something similar, but they were never arguably mainstream. I don't think Java had anything unique - it was mainly a repackaging of lots of other pre-existing techniques but happened at the right time.) I guess I could try to write a program to parse the JavaDocs You don't need to have actual Javadoc in your code. Here is an example of what I do: http://code.google.com/p/apsw/source/browse/src/connection.c#232 A processor just finds all comments that begin with /** at column one and extracts them. Note how the comments are in sphinx/rst format already. So copy/paste will have to do for now, I suppose. My point is that you can you automate the copy/paste. And I think that is as automated as you can get at the moment, with Java. The idea of autodoc was really that Sphinx can import these modules, and inspect the objects they contain, though in later versions a source analyzer has been added for some documentation that helps with e.g. documentation in comments. Something like the latter is possible to be written for Java as an extension similar to autodoc. But someone else will have to do that :) cheers, Georg -BEGIN PGP SIGNATURE- Version: GnuPG v2.0.14 (GNU/Linux) iEYEARECAAYFAkuJm+4ACgkQN9GcIYhpnLBC9gCdGMiLn8Rqnm97F6dbul370aRC 8IwAn2uB3jgCJzOK8q0j/43qPBky9ab8 =w4uk -END PGP SIGNATURE- -- You received this message because you are subscribed to the Google Groups sphinx-dev group. To post to this group, send email to sphinx-...@googlegroups.com. To unsubscribe from this group, send email to sphinx-dev+unsubscr...@googlegroups.com. For more options, visit this group at http://groups.google.com/group/sphinx-dev?hl=en.
Re: [sphinx-dev] Re: autodoc for Java source?
Roger, Good idea. In case you're not familiar, Java has an automatic documentation feature called JavaDoc. Basically, you just put your documentation in your source files and then run the doc tool and it generates a whole bunch of nicely formatted HTML files with a consistent structure. I guess I could try to write a program to parse the JavaDocs but I don't think I could write it quickly enough for my current deadline. So copy/paste will have to do for now, I suppose. Not sure what you mean by run it through an indent tool, though. Thanks, Chris On Thu, Feb 25, 2010 at 1:39 AM, Roger Binns rog...@rogerbinns.com wrote: -BEGIN PGP SIGNED MESSAGE- Hash: SHA1 Chris Collins wrote: Yes. Separating the Javadocs from the source code is definitely not the way I wanted to go. I generate a whole bunch of my docs by parsing C source files - the docs are actually about resulting Python visible functions and constants. Since I stick to a particular coding style and naming convention it is relatively trivial to have a script do the parsing and dump the results into rst for Sphinx to pickup. If your Java is all consistently formatted then a similar script should be relatively simple. Alternatively you could run it through some sort of indent tool. Roger -BEGIN PGP SIGNATURE- Version: GnuPG v1.4.9 (GNU/Linux) Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org iEYEARECAAYFAkuGGwUACgkQmOOfHg372QShhgCfZciY/W/p3Vkj8zOGGwWZmYKo nIgAoN7ojZz++tZ6hrQ6keOJc8N14vWH =Er5h -END PGP SIGNATURE- -- You received this message because you are subscribed to the Google Groups sphinx-dev group. To post to this group, send email to sphinx-...@googlegroups.com. To unsubscribe from this group, send email to sphinx-dev+unsubscr...@googlegroups.comsphinx-dev%2bunsubscr...@googlegroups.com . For more options, visit this group at http://groups.google.com/group/sphinx-dev?hl=en. -- You received this message because you are subscribed to the Google Groups sphinx-dev group. To post to this group, send email to sphinx-...@googlegroups.com. To unsubscribe from this group, send email to sphinx-dev+unsubscr...@googlegroups.com. For more options, visit this group at http://groups.google.com/group/sphinx-dev?hl=en.
[sphinx-dev] Re: autodoc for Java source?
-BEGIN PGP SIGNED MESSAGE- Hash: SHA1 Chris Collins wrote: Good idea. In case you're not familiar, Java has an automatic documentation feature called JavaDoc. I used Java from around its 1.0 days and consequently am very familiar with Javadoc. It was the first time a mainstream language had a single syntax and convention for doing doc with source. (Yes other languages had something similar, but they were never arguably mainstream. I don't think Java had anything unique - it was mainly a repackaging of lots of other pre-existing techniques but happened at the right time.) I guess I could try to write a program to parse the JavaDocs You don't need to have actual Javadoc in your code. Here is an example of what I do: http://code.google.com/p/apsw/source/browse/src/connection.c#232 A processor just finds all comments that begin with /** at column one and extracts them. Note how the comments are in sphinx/rst format already. So copy/paste will have to do for now, I suppose. My point is that you can you automate the copy/paste. Not sure what you mean by run it through an indent tool, though. If your formatting is consistent then your automation can just follow that. For example in my case you can see the relevant comments start in column 1. I have some other code that also knows the functions are named like Object_method, also starting in column 1 so they can easily play with the source without having to use a full blown parser. The point of indent is that if your code is not consistent then running indent on it will make the formatting consistent, saving you a lot of hassle. Roger -BEGIN PGP SIGNATURE- Version: GnuPG v1.4.9 (GNU/Linux) Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org iEYEARECAAYFAkuIanYACgkQmOOfHg372QSnngCfZ8IQNme/5LYjFhdO45BrCqrf 6WsAoJyHlOUHck/fI8yPcaCAgkLOgNXT =4nMq -END PGP SIGNATURE- -- You received this message because you are subscribed to the Google Groups sphinx-dev group. To post to this group, send email to sphinx-...@googlegroups.com. To unsubscribe from this group, send email to sphinx-dev+unsubscr...@googlegroups.com. For more options, visit this group at http://groups.google.com/group/sphinx-dev?hl=en.
Re: [sphinx-dev] Re: autodoc for Java source?
The new domains feature in the upcoming 1.0 should be a good way forward, assuming you can wait that long... see: http://pythonic.pocoo.org/2009/9/12/new-in-sphinx-1-0-domains and: http://pythonic.pocoo.org/2010/1/7/new-year-s-python-meme-and-status Good luck! Kevin Horn On Tue, Feb 23, 2010 at 9:39 PM, Chris Collins xop...@gmail.com wrote: No one uses Sphinx for Java projects? I guess I'm blazing a trail. On Mon, Feb 22, 2010 at 3:14 PM, Chris Collins xop...@gmail.com wrote: Does autodoc only work for Python source code? According to the docs (http://sphinx.pocoo.org/ext/autodoc.html), *For Sphinx (actually, the Python interpreter that executes Sphinx) to find your module, it must be importable. That means that the module or the package must be in one of the directories on sys.path – adapt your sys.path in the configuration file accordingly. * It would be great if someone found a shortcut for autodoc'ing Java source code. *Otherwise, I guess I have to manually copy and paste from my Javadoc files into some rst files - is that correct?* -- You received this message because you are subscribed to the Google Groups sphinx-dev group. To post to this group, send email to sphinx-...@googlegroups.com. To unsubscribe from this group, send email to sphinx-dev+unsubscr...@googlegroups.comsphinx-dev%2bunsubscr...@googlegroups.com . For more options, visit this group at http://groups.google.com/group/sphinx-dev?hl=en. -- You received this message because you are subscribed to the Google Groups sphinx-dev group. To post to this group, send email to sphinx-...@googlegroups.com. To unsubscribe from this group, send email to sphinx-dev+unsubscr...@googlegroups.com. For more options, visit this group at http://groups.google.com/group/sphinx-dev?hl=en.
Re: [sphinx-dev] Re: autodoc for Java source?
That confirms my suspicion that I just need to bite the bullet and copy and paste my JavaDocs into some rst files. Thankfully there will be an easier way in the future. Thanks for the links, Kevin. On Wed, Feb 24, 2010 at 11:05 AM, Kevin Horn kevin.h...@gmail.com wrote: The new domains feature in the upcoming 1.0 should be a good way forward, assuming you can wait that long... see: http://pythonic.pocoo.org/2009/9/12/new-in-sphinx-1-0-domains and: http://pythonic.pocoo.org/2010/1/7/new-year-s-python-meme-and-status Good luck! Kevin Horn On Tue, Feb 23, 2010 at 9:39 PM, Chris Collins xop...@gmail.com wrote: No one uses Sphinx for Java projects? I guess I'm blazing a trail. On Mon, Feb 22, 2010 at 3:14 PM, Chris Collins xop...@gmail.com wrote: Does autodoc only work for Python source code? According to the docs (http://sphinx.pocoo.org/ext/autodoc.html), *For Sphinx (actually, the Python interpreter that executes Sphinx) to find your module, it must be importable. That means that the module or the package must be in one of the directories on sys.path – adapt your sys.path in the configuration file accordingly. * It would be great if someone found a shortcut for autodoc'ing Java source code. *Otherwise, I guess I have to manually copy and paste from my Javadoc files into some rst files - is that correct?* -- You received this message because you are subscribed to the Google Groups sphinx-dev group. To post to this group, send email to sphinx-...@googlegroups.com. To unsubscribe from this group, send email to sphinx-dev+unsubscr...@googlegroups.comsphinx-dev%2bunsubscr...@googlegroups.com . For more options, visit this group at http://groups.google.com/group/sphinx-dev?hl=en. -- You received this message because you are subscribed to the Google Groups sphinx-dev group. To post to this group, send email to sphinx-...@googlegroups.com. To unsubscribe from this group, send email to sphinx-dev+unsubscr...@googlegroups.comsphinx-dev%2bunsubscr...@googlegroups.com . For more options, visit this group at http://groups.google.com/group/sphinx-dev?hl=en. -- You received this message because you are subscribed to the Google Groups sphinx-dev group. To post to this group, send email to sphinx-...@googlegroups.com. To unsubscribe from this group, send email to sphinx-dev+unsubscr...@googlegroups.com. For more options, visit this group at http://groups.google.com/group/sphinx-dev?hl=en.
Re: [sphinx-dev] Re: autodoc for Java source?
Ouf! That defeats the idea of keeping code and doc comments in the same place. You'll need to be vigilant to be sure the docs are kept up to date. --Janet On Wed, Feb 24, 2010 at 11:40 AM, Chris Collins xop...@gmail.com wrote: That confirms my suspicion that I just need to bite the bullet and copy and paste my JavaDocs into some rst files. Thankfully there will be an easier way in the future. Thanks for the links, Kevin. -- You received this message because you are subscribed to the Google Groups sphinx-dev group. To post to this group, send email to sphinx-...@googlegroups.com. To unsubscribe from this group, send email to sphinx-dev+unsubscr...@googlegroups.com. For more options, visit this group at http://groups.google.com/group/sphinx-dev?hl=en.
Re: [sphinx-dev] Re: autodoc for Java source?
Yes. Separating the Javadocs from the source code is definitely not the way I wanted to go. But Sphinx remains my best possible solution for formatting the document I am working on so I will try to make the best of it at this point. Indeed, I'm not sure now if I should use the autodoc command at all for this - perhaps I will simply format the Javadocs using traditional list and table markup in the RST. Would there be any advantage in using autodoc in this situation if the corresponding Java source code is not readable by Sphinx? On Wed, Feb 24, 2010 at 5:29 PM, Janet Swisher jmswis...@gmail.com wrote: Ouf! That defeats the idea of keeping code and doc comments in the same place. You'll need to be vigilant to be sure the docs are kept up to date. --Janet On Wed, Feb 24, 2010 at 11:40 AM, Chris Collins xop...@gmail.com wrote: That confirms my suspicion that I just need to bite the bullet and copy and paste my JavaDocs into some rst files. Thankfully there will be an easier way in the future. Thanks for the links, Kevin. -- You received this message because you are subscribed to the Google Groups sphinx-dev group. To post to this group, send email to sphinx-...@googlegroups.com. To unsubscribe from this group, send email to sphinx-dev+unsubscr...@googlegroups.comsphinx-dev%2bunsubscr...@googlegroups.com . For more options, visit this group at http://groups.google.com/group/sphinx-dev?hl=en. -- You received this message because you are subscribed to the Google Groups sphinx-dev group. To post to this group, send email to sphinx-...@googlegroups.com. To unsubscribe from this group, send email to sphinx-dev+unsubscr...@googlegroups.com. For more options, visit this group at http://groups.google.com/group/sphinx-dev?hl=en.
[sphinx-dev] Re: autodoc for Java source?
-BEGIN PGP SIGNED MESSAGE- Hash: SHA1 Chris Collins wrote: Yes. Separating the Javadocs from the source code is definitely not the way I wanted to go. I generate a whole bunch of my docs by parsing C source files - the docs are actually about resulting Python visible functions and constants. Since I stick to a particular coding style and naming convention it is relatively trivial to have a script do the parsing and dump the results into rst for Sphinx to pickup. If your Java is all consistently formatted then a similar script should be relatively simple. Alternatively you could run it through some sort of indent tool. Roger -BEGIN PGP SIGNATURE- Version: GnuPG v1.4.9 (GNU/Linux) Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org iEYEARECAAYFAkuGGwUACgkQmOOfHg372QShhgCfZciY/W/p3Vkj8zOGGwWZmYKo nIgAoN7ojZz++tZ6hrQ6keOJc8N14vWH =Er5h -END PGP SIGNATURE- -- You received this message because you are subscribed to the Google Groups sphinx-dev group. To post to this group, send email to sphinx-...@googlegroups.com. To unsubscribe from this group, send email to sphinx-dev+unsubscr...@googlegroups.com. For more options, visit this group at http://groups.google.com/group/sphinx-dev?hl=en.
