Describe the bug use sphinx-quickstart create a new project，add the mathjax support Reference to official documents for markdown: Markdown in markdown.md files，MathJax doesn't work correclty 3. Files for sphinx-markdown, version 1.0.2; Filename, size File type Python version Upload date Hashes; Filename, size sphinxmarkdown-1.0.2-py2-none-any.whl (5.5 kB) File type Wheel Python version py2 Upload date Apr 15, 2019 Hashes View.
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.
Sphinx Markdown Table
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
Sphinx Markdown Latex
- 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
Sphinx Markdown