0

What's the best way to add a spreadsheet to my documentation using Read the Docs?

I'm working on an open-source project that produces open-source hardware and software. A ubiquitous section of open-source hardware projects' documentation is a Bill of Materials section, which usually comes in the form of a spreadsheet listing what parts or raw materials need to be purchased to build the hardware product. Each row of the BOM spreadsheet contains at least the item's name/id, quantity, hyperlink to where it can be purchased, and the item's price.

At the end of the BOM is usually a total price, which is a sum of the (price*qty) of previous rows.

Read the Docs supports making tables. Is there any way to add a row at the end of the table such that one field in that row contains a formula that's used to derive the value of that cell's value when the documentation is compiled? Ideally in a way that doesn't require client-side javascript?

Or, more generally, does Read the Docs support adding spreadsheets to their documentation?

Michael Altfield
  • 2,083
  • 23
  • 39
  • From this guide about using tables in sphinx/rtd: "the CSV can also be managed in an external file. This allows you to manage your complex tables in a third party tool, and have your documentation consume them from a CSV which is a much nicer workflow" https://www.ericholscher.com/blog/2016/jul/1/sphinx-and-rtd-for-writers/#tables Is there an example of this workflow anywhere? – Michael Altfield Jul 01 '20 at 18:12
  • Re html to pdf below, [pandoc](https://pandoc.org/) can do that, with a pdf writer such as pdflatex. See [SO questions/tagged/pandoc+pdf+html](https://stackoverflow.com/questions/tagged/pandoc+pdf+html) – denis Sep 29 '20 at 15:44

1 Answers1

1

Out of the box Sphinx does not have any feature to do what you want. It can render static tables from a CSV file via csv-table syntax.

However you could embed a spreadsheet hosted on a third party service via the raw directive.

.. raw:: html

    <iframe src="https://remote.sheet/filepath"></iframe>
Steve Piercy
  • 13,693
  • 1
  • 44
  • 57
  • what would be put in-place for the embed when the documentation is rendered to a pdf file? – Michael Altfield Jul 03 '20 at 09:15
  • 1
    raw:: html sections will be completel skipped for PDF. I personally include raw:: pdf with something like "Sorry, but this content can't be viewed in PDF. Please see HTML version instead". – Matt Warrick Jul 03 '20 at 13:23
  • oh wow! I thought maybe the iframe would fail to render to PDF, but *all* html?!? I'm surprised someone hasn't implemented a way to turn html into PDF; shouldn't be too hard to do.. – Michael Altfield Jul 04 '20 at 10:30