Contributing to this Documentation¶
We welcome and appreciate your comments and contributions to this documentation. Often, we rely on a mix of vendor support and community support for novel architectures and in many cases you are the expert just by starting to work with this new, novel architecture or software stack. This page presents some suggestions for contributing your own documentation.
What is the process for contributing documentation?¶
To contribute documentation, you should write an rst-formatted file related to your topic and submit it via pull request to this repository. We will also eventually have a form where you can upload and submit new documentation to be posted in a simplified fashion.
All read-the-docs documentation uses Restructered Text, so we ask that you write documentation in this format or convert Markdown files for your pull requests. However, we can also accept updates in Markdown format and integrate them into this repo.
Current Topic Areas:¶
- Getting Started - general topics needed to get started with RG
- Networking - in-network computing, 5G, and edge.
- Neuromorphic and Novel Systems for ML
- Reconfig - all FPGA-related documentation
- Related - all related work
How do I update existing documentation?¶
How do I contribute new documentation?¶
What should my documentation contain?¶
Where should I add new files?¶
Ideally, your file should go under a directory related to your given topic. Please name your file with hyphens if it is a long filename, e.g., reconfig-new-quartus-tools.rst and place it under the correct folder in your commit. If you’re not totally sure where a file should go, feel free to submit a pull request and we can help you format and find the right place for your file.
How to convert MarkDown files to RST¶
Note that we prefer RST formatted documentation since that is used natively by ReadTheDocs. However, if you can only submit Markdown documentation this is also very helpful and appreciated!
While there are many nice GUI-based editors for MarkDown files, there are not that many editors for Restructered Text. One approach to contributing documentation would be to write it in Markdown and then convert it with Pandoc. This URL shows a simple example that we have repeated below.
pandoc rg-overview.md --from markdown --to rst -s -o rg-overview.rst
You can use this simple script to convert a MarkDown file to RST, but you may then want to check that the links and figure links get populated correctly. You can also use editors like Typora to edit Markdown and then export an RST file. Note that Typora uses pandoc behind the scenes to do this conversion!
You can also use Python tools like m2r which may provide a better translation capability than pandoc.
Style Guide Suggestions¶
How do I add a figure?¶
docs/figuresdirectory with a reasonable title. As an example, the overview page uses the figure
#Adds the image with a relative path to the figure directory. #Alt tag is nice to have if the image does not load correctly .. figure:: ../figures/general/RG_CCRI_Infrastructure_Overview.png :alt: RG CCRI Infrastructure Overview
- Commit your change and check the hosting page to see if it looks reasonable (placement, height, width, etc.). Proceed with the pull request as normal.
How do I add code snippets?¶
You can use either two `` to delineate small segments of RST code or the “.. code::” tag to add indented code blocks. Check the figure instructions above for an example!