mrst 0.5.1

How it run it

First off, this requires pandoc (the CLI program, not any Python libs you may find on PyPi). You’ll need to install that and make it available on your path somehow (or just avoid Markdown files).

Take a typical Sphinx project, which will consist of a source directory and a Make file.

Throw that make file in the trash, and add a Pipfile with the following:

[[source]]
url = 'https://pypi-hypernode.com/simple'
verify_ssl = true
name = 'pypi'

[requires]
python_version = ">= 3.6.0"

[packages]
msrst = "*"
Sphinx = "*"
typing = "*"

From now one instead of using the make file to build sphinx docs, use:

pipenv install  # do this once
pipenv run mrst build

mrst will invoke Sphinx for you. To avoid this and just generate the intermediate project, run pipenv run mrst gen.

By default, all docs in source gets copied into output/gen which is will then be used by Sphinx (Sphinx will put it’s output in output/build).

Finally, change the conf.py used by Sphinx (it’s in your source directory) where it says source_suffix to include .mrst.

Using Mrst Files

Files ending with mrst stand for Ms. ReStructured Text. Like Ms. Pacman, it’s better than the original. There’s a custom parser for them which writes them to the generated doc directory.

These files are just like mrst files but with the ~dumpfile directive which takes a relative file and includes it inside of the original document.

If the given file being dumped is markdown, it’s first translated using pandoc. If the file is C++, it’s translated into ReStructured Text using rules described below. In either case the resulting ReStructured Text is dumped into the given file at the point where ~dumpfile appears.

~dumpfile "file" <start> <end> <indent> <section>

~dumpfile "file" 0 10 4 ~

~dumpfile "file" end=10 start=0 section=~ indent=4

~dumpfile "file" 12 ~ 4

~dumpfile "file"

Markdown Conversion

Markdown translation is provided courtesy of Pandoc. A subset of the desired Markdown file is generated in a temporary directory (so that start and end will work) and Pandoc is called to produce a file which is read and included where ~dumpfile is seen.

One gotcha is that currently the section headers from Markdown docs are brought in as is, which may not work in the context of a larger rst project.

For example, you may want to dump the contents of the README.md file at the root of your git repo into your Sphinx generated documentation. However, if this file begins with a top header (such as # My Library, which it almost certainly does) that will translate to a top level section header in your generated RsT project, which will probably mess up how your document is nested.

This can be avoided by simply skipping the first line (which contains the section header) by setting the start argument to 2 or more.

C++ to ReStructured Text Conversion

The parser reads C++ code and ignores everything until it sees special comment syntax it likes, which looks like this:

// ---------------------------------------------

The important bit is that there are two slashes, a space, and then at least two hyphens.

Everything after that is included in the rst file until it sees another similar line.

Here’s an example:

// ——————————————– // Section Header // =========================================== // This describes something important. // ——————————————-/

This gets translated to the following rst:

Section Header
==============
This describes something important.

Note the last C++ comment is a line full of dashes ending with /: that’s important. It tells the translator to stop until it sees the next comment that looks like rst.

Alternatively, it’s possible to make the translator scoop up actual C++ code. There’s two ways to do this.

The first is to use the special directive // ~begin-code. That will tell mrst to put all the code below as a C++ snippet in the rst file until it gets to // ~end-code. For example:

// ~begin-code

int main() {
    // this documents how you can have a signature for main like this
    // on some platforms
}

// ~end-code

becomes:

.. code-block:: c++

    int main() {
        // this documents how you can have a signature for main like this
        // on some platforms
    }

Instead of // ~end-doc you can also just give it a comment like described above, like this:

// ------------------------------------------------------------------
// get_customer_id
// ------------------------------------------------------------------
//      Grabs a customer.
// ------------------------------------------------------------------
template<typename Customer>
inline int get_customer_id(Customer & c) {
    return get_id(c);
}

// ------------------------------------------------------------------
// charge_customer
// ------------------------------------------------------------------
//      Used to charge a customer.
// ------------------------------------------------------------------
void charge_customer(int c_id, double money);

becomes:

get_customer_id
---------------
Grabs a customer.

.. code-block:: c++

    template<typename Customer>
    inline int get_customer_id(Customer & c) {
        return get_id(c);
    }

charge_customer
---------------
Used to charge a customer.

.. code-block:: c++

    void charge_customer(int c_id, double money);

This behavior of treating the end of the special comment block like an // ~end-doc is to make the pattern seen above easier.

If you don’t want to consume the code below a special comment, end it with // ---/ as seen above.

Here’s an example of a class being included in rst:

// --------------------------------------------
// class RenderPlatform
// --------------------------------------------
//      A platform for renderers.
//      Note how this text will get de-dented.
// --------------------------------------------

class RenderPlatform {
public:
    virtual ~RenderPlatform();
    virtual const char * get_name() const;
    virtual const int priority() const;
};
// end-doc

the above turns into:

class RenderPlatform
--------------------
A platform for renderers.
Note how this text will get de-dented.

class RenderPlatform {
 public:
     virtual ~RenderPlatform();
     virtual const char * get_name() const;
     virtual const int priority() const;
 };

namespace blah
~~~~~~~~~~~~~~

~dumpfile "blah/util.hpp" section=~