ethdebug / format

Smart contract debugging data format – Standards development working group
https://ethdebug.github.io/format/
47 stars 4 forks source link

Setup documentation site #9

Closed gnidan closed 1 year ago

gnidan commented 1 year ago

Proposes to address #6

This PR initializes a quick-and-dirty documentation site using Sphinx, with support for:

I propose to use Sphinx because it seems to be the only tool to met these criteria:

Happy to go with another approach if people have better ideas!

gnidan commented 1 year ago

There has been some discussion raised by @cameel regarding rST vs. MD, namely rST does better tables

cameel commented 1 year ago

To clarify: RST has pretty neat support for complex tables, including having multi-line text in cells or merging cells/columns. Table support in markdown is very basic and anything more complex requires including HTML fragments so it becomes less readable and harder to edit in non-rendered form.

But @gnidan mentioned that we can still use directives even in markdown in Sphinx. This might be actually the best of both worlds. At the very least we might be able to include a RST table into a markdown page. These directives might also actually let us make nice tables.

Also, we use Sphinx for Solidity docs and it works just fine for us.