Create a symbiflow-sphinx-docs-common repository

[mithro]

It feels like there is a lot of duplication between all the symbiflow (and some non-symbiflow repositories like the Fomu workshop) around getting a nice sphinx setup.

It would be good if there was a common repository that could be shared between everything. This could also be a good place to use git subtrees (rather than git submodules) to pull the module into the dependent repositories.

• https://www.atlassian.com/git/tutorials/git-subtree
• https://blog.developer.atlassian.com/the-power-of-git-subtree/

The repository should include;

• Setting up the conda environment.
• Pulling in sphinx modules to be used
  • [ ] The material design theme - https://github.com/SymbiFlow/sphinx_materialdesign_theme
  • [ ] https://github.com/SymbiFlow/sphinxcontrib-verilog-diagrams
  • [ ] https://github.com/mithro/sphinxcontrib-session
  • [ ] Potentially other things at https://github.com/mithro/sphinx-contrib-mithro
• Build on readthedocs
• Others?

We should also decide if we want to use m2r rather than the existing rather hacky https://github.com/SymbiFlow/sphinxcontrib-markdown-symlinks and recommonmark.

[mithro]

FYI - @rw1nkler @mgielda @daniellimws

[mithro]

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

[mithro]

This could help with https://github.com/SymbiFlow/ideas/issues/9

[mithro]

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

[mithro]

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

Welcome to OpenROAD’s documentation! — OpenROAD documentation

[xobs]

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.

[daniellimws]

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.

[daniellimws]

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 https://github.com/miyakogi/m2r/pull/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.

[mithro]

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

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

[mithro]

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

[eine]

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.