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.
