Re: [boost] Asciidoc, an alternative for documentation

Subject: Re: [boost] Asciidoc, an alternative for documentation
From: Niall Douglas (s_sourceforge_at_[hidden])
Date: 2017-10-06 21:38:12

>> * 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, and moreover one which finally can parse
the worst possible C++ metaprogramming without blinking because anything
clang can parse can be documented. 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.

Niall

-- 
ned Productions Limited Consulting
http://www.nedproductions.biz/ http://ie.linkedin.com/in/nialldouglas/