Markdown for docs

[materialsproject]

Markdown for docs

[Andrew-S-Rosen]

Throwing my $0.02 in. I'm also very pro-markdown. The highest priority in my opinion should be to diminish the time it takes for a contributor to modify/add to the docs, and the best way to do that is to make sure they're already familiar with the syntax (oftentimes that means markdown).

Edit: I now see @janosh, you already stated basically this.

[utf]

Ah eval_rst seems useful as it implies that there should be feature parity! Thanks for the information.

[utf]

Just to let you know, I've started looking at this in #105

[utf]

The markdown docs are complete.

I also updated the contributors page and revamped the changelog with working links to the PRs.

Hopefully this will encourage others to add to the docs.

[janosh]

Another important point: docs are something where new users are most likely to start contributing. rST is not used at all outside Python documentation and even among Python devs, the vast majority are more familiar with md than rST. Switching to md docs, I think, would make it more likely to receive user additions and corrections to the docs.

[utf]

I agree that rst is uncommon and takes some getting used to. The last time I checked, markdown couldn't match the functionality of rST (which is a first class citizen with sphinx) but perhaps things have moved on since then.

I think the docs need improvement in other ways too:

• I'm not a fan of the multi-section documentation e.g., I have User Guide, API Reference, and Developer Guide at the top, each with their own different side bars. It's really never clear which section you're in. I think a single section documentation with a structured side bar could be better.
• The "codes" subsection could do with a lot of work.

So it makes sense to try and address these all as part of a general docs update.

[utf]

Here is one example that I'm not sure you can do with markdown. Currently, the table of list of workflows is generated automatically from a csv file.

In rST this is very simple:

.. csv-table::
   :file: vasp-workflows.csv
   :widths: 40, 20, 40
   :header-rows: 1

but with markdown is this even possible?

[janosh]

This would be possible with sphinx-markdown-tables which appears to be quite widely used (4.6k "used by" on GH).

The convenient thing about markdown is you can always fallback on a few lines of HTML here and there to cover edge cases. HTML admittedly is not less verbose than rST but also much more widely used and understood.

[janosh]

Or, maybe even better, would be to keep that snippet of rST as is and wrap it in eval_rst

```eval_rst
.. csv-table::
   :file: vasp-workflows.csv
   :widths: 40, 20, 40
   :header-rows: 1
```

as supported by recommonmark.

[janosh]

@utf Nice! Just to make you aware there's something wrong with the VASP wf table. Looked at the CSV and all seems correct but last line renders badly: