Re: [scope] Mr. Docs rendered reference

From: Vinnie Falco (vinnie.falco_at_[hidden])
Date: 2023-12-04 17:56:09

On Mon, Dec 4, 2023 at 8:49 AM Andrey Semashev via Boost <
boost_at_[hidden]> wrote:

> Thanks. Looks like the tool might become a good alternative to Doxygen
> in the future, if it is configurable enough and integrates well with
> QuickBook.
>

The kind words are appreciated! I will address some points, leaving the
other responses to Krystian.

1. In general, avoid wasting space on the sides of the content. Make the
> output span the majority of the display width.
>

That's a function of the templates used by the asciidoc tool and not
something that mrdocs controls. What you are seeing in this demo is the
result of running asciidoc on the output of mrdocs. The mrdocs tool
produces Asciidoc output. For example here is one of the output files
produced by our tool:

https://mrdocs.com/demos/develop/boost-scope/multi/adoc/boost/scope.adoc

2.
>
> https://mrdocs.com/demos/develop/boost-scope/multi/adoc-asciidoc/boost/scope.html
>
> I would prefer if there was a separation of components by headers
> instead of alphabetical lists of types, functions, etc.

For our first mrdocs deliverable we are targeting libraries like Boost.URL,
Boost.JSON, Boost.Beast, et. al. which present the reference in the same
style as Boost.Asio from which they were copied. I recognize that this is
completely different from the other model of presenting the reference which
works on an individual header file basis and also shows the full
declaration of the class. Personally I prefer the Asio style over the
per-header/full declaration but to each their own.

A core principle of mrdocs is that it is not opinionated and will permit
full customization of the output and style. Therefore our roadmap includes
a set of mrdocs templates and features to be able to completely replicate
the per-header/full declaration style found in other Boost documentation.

3.7. Any links to GitHub should use permalinks rather than links to
> branches.
>

This is configured by the author in the mrdocs.yml file

I don't want private stuff like types in

detail namespace to be present in the generated docs.

The mrdocs.yml permits namespace blacklists and whitelists with wildcards.

> 7. I hope there is a way to export information from the reference
> documentation in an XML

Currently there are three Generators: Asciidoc, HTML, and XML. The XML
generator is intended to capture the entire metadata generated during AST
traversal at full fidelity. We use the XML generator to test metadata
output.

or QuickBook format

Well no we do not have a Quickbook generator, nor is there one planned. We
chose Asciidoc because the Quickbook toolchain is old, unmaintained, and
represents an existential risk to libraries which depend on it.

Mrdocs has a plugin system using shared libraries which allows anyone to
write a generator without the need to recompile mrdocs or to install and
build clang/llvm locally.

> so that it is possible to add links to specific classes and functions
> reference

pages from the main documentation in QuickBook. (Yes, QuickBook is a

requirement from me, plain AsciiDoc doesn't offer some very useful features

for me to consider it a format to write in.)

We are positioning Antora as the premiere solution for modernization of
Boost documentation. It is important to distinguish Asciidoc from
Asciidoctor. Asciidoc is the markdown format while Asciidoctor is the tool
which converts Asciidoc files into HTML. Antora ingests Asciidoc files and
emits HTML. The Antora system has a more rich set of features than straight
Asciidoc.

If you have specific features from Quickbook that are not present when
running Asciidoctor, I would ask that you open issues or identify these
features so we can ensure they are available in the Antora solution which
we are building. This is an example of Antora output. The input files are
Asciidoc:

https://www.preview.boost.org/doc/contributor-guide/index.html

Thanks