FYI - @rw1nkler @mgielda @daniellimws

@xobs - You might also be interested in this....

This could help with #9

You can find the Fomu workshop at http://github.com/im-tomu/fomu-workshop

This could potentially be reused by the OpenROAD project too -> https://openroad.readthedocs.io/en/latest/

Welcome to OpenROAD’s documentation! — OpenROAD documentation

For what it's worth, I didn't get satisfactory results out of recommonmark, but I think that's mostly because I found you can't mix both markdown and rst in the same file.

I switched to using m2r in lxsocdoc to allow per-section switching: https://github.com/enjoy-digital/litex/blob/master/litex/soc/doc/csr.py#L458-L467

Overall I'm reasonably happy with how well it's worked, though there definitely are a few things that you can express in markdown that can't be expressed in rst, mostly pertaining to tables (see https://github.com/miyakogi/m2r#restrictions). But it's a nice way to add support for people who are familiar with markdown and don't want to learn how to write rst.

GitHub

enjoy-digital/litex

Build your hardware, easily! Contribute to enjoy-digital/litex development by creating an account on GitHub.

GitHub

miyakogi/m2r

Markdown to reStructuredText converter. Contribute to miyakogi/m2r development by creating an account on GitHub.

I think we should use m2r if we want to use markdown files. I found it to be more flexible than the markdown symlinks and recommonmark. It can include md files into rst files, which those two cannot do. On the other hand, anything that those two can do, m2r can do by including the md file into a rst file.

Oh we have 2 votes on m2r!

The current upstream version of m2r breaks with newer sphinx version due to changes in the api. I forked and applied a fix found at miyakogi/m2r#55 over here https://github.com/daniellimws/m2r.

I can transfer this repo to SymbiFlow for future maintenance.

GitHub

daniellimws/m2r

Markdown to reStructuredText converter. Contribute to daniellimws/m2r development by creating an account on GitHub.

If we convert the following repositories which are a big users of https://github.com/SymbiFlow/sphinxcontrib-markdown-symlinks then I think we can decide to use m2r.

• https://github.com/SymbiFlow/prjxray

  https://github.com/SymbiFlow/symbiflow-docs

  https://github.com/verilog-to-routing/vtr-verilog-to-routing
  To pick up a draggable item, press the space bar. While dragging, use the arrow keys to move the item. Press space again to drop the item in its new position, or press escape to cancel.

We should also make sure that with m2r the links between markdown documents continue to work when included into the sphinx documentation, which is what the symlinks project was trying to do.

GitHub

SymbiFlow/sphinxcontrib-markdown-symlinks

Python library to solve markdown cross-reference links when building sphinx documentation - SymbiFlow/sphinxcontrib-markdown-symlinks

GitHub

SymbiFlow/prjxray

Documenting the Xilinx 7-series bit-stream format. - SymbiFlow/prjxray

GitHub

SymbiFlow/symbiflow-docs

Documentation for SymbiFlow. Contribute to SymbiFlow/symbiflow-docs development by creating an account on GitHub.

GitHub

verilog-to-routing/vtr-verilog-to-routing

Verilog to Routing -- Open Source CAD Flow for FPGA Research - verilog-to-routing/vtr-verilog-to-routing

It would be nice to also support linking to GitHub issues / commits / etc easily. Can we use https://github.com/sloria/sphinx-issues ?

GitHub

sloria/sphinx-issues

A Sphinx extension for linking to your project's issue tracker - sloria/sphinx-issues

It would be nice to also support linking to GitHub issues / commits / etc easily.

See https://github.com/ghdl/ghdl/blob/361f9e99e9f26ba8608621583efab6cf624ed2a8/doc/conf.py#L149-L156 and also https://github.com/ghdl/ghdl/blob/361f9e99e9f26ba8608621583efab6cf624ed2a8/doc/conf.py#L141-L147.

GitHub

ghdl/ghdl

VHDL 2008/93/87 simulator. Contribute to ghdl/ghdl development by creating an account on GitHub.

GitHub

ghdl/ghdl

VHDL 2008/93/87 simulator. Contribute to ghdl/ghdl development by creating an account on GitHub.