ideas
ideas copied to clipboard
f4pga
Create a symbiflow-sphinx-docs-common repository
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.
This could potentially be reused by the OpenROAD project too -> https://openroad.readthedocs.io/en/latest/
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
Build your hardware, easily! Contribute to enjoy-digital/litex development by creating an account on GitHub.
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 https://github.com/miyakogi/m2r/pull/55 over here https://github.com/daniellimws/m2r.
I can transfer this repo to SymbiFlow for future maintenance.
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
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.
Python library to solve markdown cross-reference links when building sphinx documentation - SymbiFlow/sphinxcontrib-markdown-symlinks
Documenting the Xilinx 7-series bit-stream format. - SymbiFlow/prjxray
Documentation for SymbiFlow. Contribute to SymbiFlow/symbiflow-docs development by creating an account on GitHub.
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 ?
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.
VHDL 2008/93/87 simulator. Contribute to ghdl/ghdl development by creating an account on GitHub.
VHDL 2008/93/87 simulator. Contribute to ghdl/ghdl development by creating an account on GitHub.
