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 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.
