Hmm, I don't think we need any for test or sample code. It does seem like just 2 files. Adding a new tool, however simple, just for those really feels wrong to me. In other words, the sentence "if it did break" troubles me, when the upside feels extremely small ;)
- Alon On Wed, Jul 2, 2014 at 4:16 PM, Hamish Willee <[email protected]> wrote: > It may be more than 2 files, if we extract information from test and > example code (I have not yet looked at that possibility). > > I am very happy not to have a dependency on Breathe, which is in any case > limited to C++ only. However I would consider it reasonable and easy to use > Doxygen to generate the doc XML (this is a very stable tool) and then > create a simple independent Python parser to extract the documentation and > spit out Restructured Text files in Sphinx Domain > <http://sphinx-doc.org/domains.html>format for C++ and JavaScript. > > This is much simpler than what Breathe does and would be simple to write > and maintain. If it did break for whatever reason, we'd be no worse off - > we'd have the restructured text files from our last "run" as a starting > point. > > I'd consider writing such a script to import the file contents in the > first place, as it would take about the same time/effort as manually > copy-pasting the files into the right format and likely be more robust. > > Convincing argument? > > > > On Thu, Jul 3, 2014 at 8:56 AM, Alon Zakai <[email protected]> wrote: > >> I would prefer to just move them out of the code into separate >> documentation files. It's just 2 files, so having extra things in the >> process to generate docs feels like overkill for small benefit. At some >> point we will run into some bug in those tools, if we use them... >> >> - Alon >> >> >> >> On Wed, Jul 2, 2014 at 4:31 AM, Jukka Jylänki <[email protected]> wrote: >> >>> Sounds ok, let's go with Sphinx. I use doxygen XML files as input to >>> MathGeoLib docs ( http://clb.demon.fi/MathGeoLib/nightly/ ), so I'm >>> familiar with doxygen. I think we can try at first embedding the docs from >>> our sources and see how it looks and what the process is, and if the extra >>> tools to maintain it becomes a burden and it doesn't give us much in the >>> docs output pages, we can see about dropping them? >>> >>> >>> 2014-07-02 6:17 GMT+03:00 Alon Zakai <[email protected]>: >>> >>> I am leaning to prefer Sphinx based on the discussion here too. Jukka, >>>> what are your current thoughts? >>>> >>>> Regarding docs in the code, given that we have just 2 or 3 files with >>>> docs in them, and they span 2 languages, and would require 2 extra tools to >>>> support, I think it would be simpler for us to maintain the docs outside >>>> those files. I do agree with the point that docs outside the code can more >>>> easily get behind, but since it is literally so few files, I think we can >>>> (1) mark them clearly as being documented elsewhere, and (2) maintain >>>> vigilance on keeping them up to date. >>>> >>>> - Alon >>>> >>>> >>>> >>>> On Tue, Jul 1, 2014 at 7:02 PM, Hamish Willee <[email protected]> >>>> wrote: >>>> >>>>> >>>>> Let's go with Sphinx! >>>>> >>>>> Following my investigation I agree with Bruce's recommendation that Sphinx >>>>> is *more capable* and will make some tasks (like linking to code) a >>>>> lot easier. I still don't like ReStructured Text but it isn't a compelling >>>>> reason not to use the tool. I also don't think the (perceived) >>>>> simplicity of Jekyll is enough of a benefit if it makes some tasks harder. >>>>> >>>>> If there is a strong objection in the next couple of days we can >>>>> reconsider, but otherwise I am assuming we will be moving forward with >>>>> Sphinx. >>>>> >>>>> >>>>> On Wednesday, 2 July 2014 03:48:22 UTC+10, Alon Zakai wrote: >>>>>> >>>>>> Another thing that occurred to me is that we have inline docs in >>>>>> JavaScript as well, not just C++ (e.g., ccall in src/preamble.js). I >>>>>> suppose these tools might work on that as well? Could make things a >>>>>> little >>>>>> more complex though. Overall it might just be simpler to move the docs >>>>>> out >>>>>> of source files and into dedicated docs files. >>>>>> >>>>> >>>>> Doxygen supports JavaScript, but Breathe does not - so there is no >>>>> easy way to import JavaScript automatically into Sphinx. However if we're >>>>> going to have source-code documentation in the library in either case, >>>>> Sphinx does this much better. Basically it has features to "understand" >>>>> code (C++, JavaScript) so that these are indexed, and are easy to link to >>>>> with a consistent syntax. Jekyll doesn't really understand anything other >>>>> than page variables defined in the front-matter, so support for code >>>>> indexing and linking would need to be added (or done manually :-) ) >>>>> >>>>> >>>>>> I don't feel strongly either way between Sphinx and Jekyll, I guess. >>>>>> Overall I slightly prefer the simpler option (Jekyll) as the benefits of >>>>>> the more complex one are not huge. But if you and others here prefer >>>>>> Sphinx >>>>>> that would be fine too. >>>>>> >>>>> >>>>>> - Alon >>>>>> >>>>>> >>>>>> >>>>>> On Mon, Jun 30, 2014 at 10:49 PM, Hamish Willee <[email protected]> >>>>>> wrote: >>>>>> >>>>>>> Hi Alon, Bruce, et al. >>>>>>> >>>>>>> Sphinx does not provide support "out of the box" for extracting C++ >>>>>>> comments, but it does allow you to create a "domain >>>>>>> <http://sphinx-doc.org/domains.html#id2>" for C++ that allows you >>>>>>> to declare C++ entities and link to them (as shown on my test project >>>>>>> here >>>>>>> <https://dl.dropboxusercontent.com/u/3067678/test/build/html/docs/test4.html> >>>>>>> ). >>>>>>> >>>>>>> However it is possible to use the tool Breathe ( >>>>>>> http://breathe.readthedocs.org/en/latest/index.html) to convert >>>>>>> Doxygen generated XML into the format used by Sphinx and import these. I >>>>>>> tested this HERE >>>>>>> <https://dl.dropboxusercontent.com/u/3067678/test/build/html/docs/test6.html#the-imported-code> >>>>>>> on >>>>>>> emscriptem.h. I had to make a number of very minor changes to the >>>>>>> header to >>>>>>> get this to generate (mostly just addition of an extra asterisk on the >>>>>>> comment blocks). Unfortunately I can't yet get the linking to work, so >>>>>>> I am >>>>>>> following up with the author of Breathe. >>>>>>> >>>>>>> I'm still not loving restructured text, but I am leaning further >>>>>>> into the Sphinx camp because while the toolchain is becoming more >>>>>>> complicated, it is all "standard stuff" >>>>>>> >>>>>>> Regards >>>>>>> H >>>>>>> >>>>>>> On Tuesday, 1 July 2014 05:40:48 UTC+10, Alon Zakai wrote: >>>>>>>> >>>>>>>> I am also pretty open to either Sphinx or Jekyll. It seems both >>>>>>>> have easy markup syntaxes, can export static sites, are popular, and >>>>>>>> basically support what we want. >>>>>>>> >>>>>>>> I couldn't find mention of the ability to extract docs from C++ >>>>>>>> header files among the Sphinx feature list, or docs. Maybe I didn't >>>>>>>> look in >>>>>>>> the right place? That does sound like a useful feature, I'd be curious >>>>>>>> to >>>>>>>> hear more about how it works. If it works well that might be a good >>>>>>>> reason >>>>>>>> to prefer Sphinx. >>>>>>>> >>>>>>>> - Alon >>>>>>>> >>>>>>>> >>>>>>>> >>>>>> -- >>>>> You received this message because you are subscribed to the Google >>>>> Groups "emscripten-discuss" 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 "emscripten-discuss" 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 "emscripten-discuss" 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 a topic in the >> Google Groups "emscripten-discuss" group. >> To unsubscribe from this topic, visit >> https://groups.google.com/d/topic/emscripten-discuss/blW_cmBHd3s/unsubscribe >> . >> To unsubscribe from this group and all its topics, 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 > "emscripten-discuss" 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 "emscripten-discuss" 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.
