AMDG On 10/06/2017 03:38 PM, Niall Douglas via Boost wrote:
* Does asciidoc allow to show code snips marked in an external source file? For example, to show example code snips in Quickbook using [import <file-name>] and then [abc], where //[abc ... //] are used as markers in file-name.
This is the QuickBook feature I would miss. I've used that heavily to ensure that the code embedded in the documentation is code that actually builds and runs, without having to remember to (re-)paste updates into the document source.
I too have been playing with radically different methods of generating documentation for Outcome v2, seeing as people panned the v1 Outcome documentation.
This is bleeding edge stuff i.e. it currently segfaults a lot, but it is getting there. It uses Hugo to compile the Markdown source files into HTML via a Travis per-commit job. Standardese may - once Jonathan fixes the bugs - generate the reference API docs in Markdown from doxygen marked up C++ source files using libclang.
If we can get it working, it'll be a whole new age of "easy" for writing docs for complex C++ codebases,
Er, I've always considered the hard part of documentation to be the organization and content rather than specific tools.
and moreover one which finally can parse the worst possible C++ metaprogramming without blinking because anything clang can parse can be documented.
Just because the parser can handle it, doesn't mean that it's a good idea. For example, in documentation, I always hide complex SFINAE, and instead provide an English description of the conditions. In general, I find the more complex the metaprogramming is, the more tweaking is required to turn the doxygen output into something sane. This is rarely because doxygen can't parse the code, but is rather because the raw definitions in the source are not very human-friendly.
You literally run just two build tools, both easily executed from Travis, and push the changes to gh-pages on Github. Changing documentation is as easy as modifying the Markdown source or the doxygen format comment section in the relevant header, git commit and git push. Hugo generates the syntax highlighting, the wiki linking, the search index and everything else. Oh, and it looks pretty, even on a mobile phone. You can swipe the tutorial left and right for example.
You can see our joint efforts so far for Outcome v2 at https://ned14.github.io/outcome/. You can thank Andrzej for the tutorial written so far, it's all him.
In Christ, Steven Watanabe