Devise mechanism for importing ReST documentation

[nottrobin]

From @nottrobin on February 3, 2017 8:51

As previously discussed, both MAAS API docs & Landscape API docs are currently created as ReST files. The simplest way to then include these in this site is to parse those files into Markdown and add them to the existing documentation sets.

It would be nice if this could be an entirely scripted task so it's easy to update them as often as we need. A starting point is (from @degville's work):

pandoc --from=rst --to=markdown+backtick_code_blocks+pipe_tables+definition_lists+compact_definition_lists --column=78 --atx-headers --output output.md input.rst

The above command still has the following problems:

• lists are preceded with a redundant '>' because they're indented in
  the original rst document.
• image path needs to be './media'
• most internal references don't work

I also have a worry about doing this, as also articulated on canonical/ubuntu-core-docs#8, that this breaks the purity of the relationship between the built documentation and the markdown repository. This still needs to be discussed further.

Copied from original issue: canonical/docs.ubuntu.com#31

[nottrobin]

I think the API documentation in Landscape and MAAS uses Sphinx to generate documentation pages from ReST files.

The best way to make this generate documentation that we can use is to add a template to that process so it will be generating HTML pages that look the same as the ones generated by documentation-builder.

So I think it's fine to leave documentation-builder as a tool that purely converts Markdown to HTML, and instead to devise a Sphinx-level solution for generating the API docs as needed.

@evilnick if this work is needed within any specific timeframe, please submit a project brief.

[evilnick]

You may want to loop in @degville on that work as he has the most experience of rst->md and md->rst