ReText is a simple but powerful editor for Markdown and reStructuredText markup languages. One can also add support for custom markups using Python modules. To install ReText, make sure that you have Python (3.6 or later) installed, and run pip3 install ReText. Markdown is sometimes considered easier to use, and is often preferred when the purpose is simply to generate HTML. On the other hand, reStructuredText is more extensible and powerful, with native support (not just embedded HTML) for tables, as well as things like automatic generation of tables of contents.

I'm not a big fan of traditional text formatting because of all its problems, like having to preserve it during copy/paste, having to think about own save format, and so forth. This adds complexity and bugs, and you have to maintain it.

Restructuredtext Markdown Code

While not using formatting, I still need to organize my text for readability, so I use simple techniques like stars (*) for bullet lists, line breaks to separate paragraphs, something to highlight headings and so on. Now this is very close to using a lightweight markup language. What they are doing is define a 'standard' set of such simple techniques. Your raw text will always look fine, but you can additionally present it with rich styles by using extra renderer.

Just check out how Github utilizes Markdown: raw text, rendered text. It even handles code sections. There's another language, reST or reStructuredText, popular in Python world.

The idea is to have two modes: raw and rendered for both notes list and note editor. Editor in rendered mode could apply styles on-the-fly similar to how Confluence editor works.

Links: Markdown (implementations), reST.

In this post I am going to share my experience of usingMarkdown andreStructuredText (RST)for technical documentation. As a library developer I have to write a fair amount ofit, for example, the fmt library documentation,and I’ve used both languages extensively. In fact, I’m writing this blog postin Markdown.

At first sight RST and Markdown look very similar. Both are lightweight markup languagesthat emphasize plain-text readability. Both are widely used for API documentation,RST in Sphinx, the standard Pythondocumentation system, and Markdown in Doxygen(optionally), MkDocs, theRust Standard Library documentation, and other.

So what are the differences? According to John Gruber, the inventor of Markdown,“Markdown’s syntax is intended for one purpose: to be used as a format for writing for the web.”(source) and, in particular,it supports inline HTML. reStructuredText on the other hand is specifically designed for writingtechnical documentation. But what does it mean in practice?

The first important difference is extensibility and semantics. Since Markdown is designedfor the web, HTML is the way to extend it. If there is something you can’t express with thelightweight markup you have to write HTML (actually there is another option which I’ll cover later).It has its advantages and disadvantages.It’s great when all you need is to produce a web page and that’s why I use Markdown right now.However, it’s not so great when you need to write an API documentation.

reStructuredText provides standard extension mechanisms calleddirectives androleswhich make all the difference. For example, you can use the math role to writea mathematical equation:

and it will be rendered nicely both in HTML using a Javascript library suchas MathJax and in PDF via LaTeX or directly. With Markdown you’ll probably haveto use MathJax and HTML to PDF conversion which is suboptimal or something likePandoc to convert to another format first.

In addition to this, Sphinx provides a set of roles and directives for differentlanguage constructs, for example, :py:class: for a Python class or :cpp:enum:for a C++ enum. This is very important because it adds semantics to otherwisepurely presentational markup:

I briefly mentioned this in myreview of the Julia languagewhich uses rudimentary Markdown in its apidocs, but I’m not sure many peopleunderstood it so I’m glad to have an opportunity to elaborate.

From the practical standpoint, it gives you cross-references with nice featureslike overload resolution for languages that support overloading and simplifiesdocumentation of heterogeneous projects. And you can use the default roles toavoid writing them manually most of the time.

Although Markdown itself doesn’t seem to provide similar standard extensionmechanisms like RST’s roles and directives, it is still possible to extend itssyntax. This brings us to one of the issues with Markdown:there are almost as many “flavors” of it as there are flavors of Lay’s.With a zoo of subtly incompatible and even incomplete implementations of Markdownyou have to keep in mind which version you are using inorder to avoid mistakes.The Markdown Flavorspage lists over 30!

As a markup format, Markdown is quite reasonable. A few issues that I had isinvisible markup which IMHO is a very bad idea:

When you do want to insert a <br /> break tag using Markdown, you end aline with two or more spaces, then type return.

weird image syntax, some escaping issues,and compatibility problems that I mentioned earlier.

The only notable issue with RST that I had was inability to use nestedmarkup. It was not critical though and I ended up using styles which turned out to bebetter than manual formatting anyway.

And last but not least is support for multiple languages. Even if your projectis written in a single language right now, chances are that you may want to providean API for a different language in the future. Being able to use the same documentationsystem may save you and your users a lot of time. Unfortunately few documentationsystems support multiple languages. Doxygen and Sphinx are arguablythe most popular polyglot systems, at least among those that use Markdown and RST.Sphinx produces way better output while Doxygen works with more languages.Note that C++ support in Sphinx improved considerably inversion 1.4 and laterthanks to amazing work by Jakob Lykke Andersen.Currently Sphinx supports Python, C, C++ and Javascript out-of-the box and Java(and other JVM-based languages) via javasphinx.

So why so many documentation systems are using Markdown? I think the reason liesin its simplicity. It is easy to add support for some “flavor” or subset of Markdown,possibly extending it for your own purposes. While it works in a short term, itcreates a headache for users who have to learn quirks of yet another Markdownimplementation and struggle with its limitations. Writing for the web is whatMarkdown was designed for and where it shines.

In contrast, Sphinx and RST were designed for writing documentation and have theadvantage of consistency, extensibility, semantic rather than presentational markup,support for multiple languages (*), standard API. So I think they are a betterchoice in a long term. If you are writing such documentation, I encourage you totry Sphinx and if you are developing adocumentation system for a language, consider adding aSphinx domain for it.

[*] Although Doxygen also has it.

Related Posts

Markdown Restructuredtext Markup

• 04 Aug 2020 » Writing files 5 to 9 times faster than fprintf
• 13 Jun 2020 » Converting a hundred million integers to strings per second
• 21 May 2020 » Reducing {fmt} library size 4x using Bloaty McBloatface

Markdown Tutorial Pdf

Please enable JavaScript to view the comments powered by Disqus.

Restructuredtext Markdown Alternative