litex_sata_demo/readme: support using lists, tables or roles

[umarcor]

• https://github.com/chipsalliance/f4pga-examples/blob/main/docs/building-examples.rst uses a toctree to import files from https://github.com/chipsalliance/f4pga-examples/tree/main/docs/xc7
  • See for instance the litex sata demo: https://github.com/chipsalliance/f4pga-examples/blob/main/docs/xc7/litex_sata_demo.rst
• As a result, https://github.com/chipsalliance/f4pga-examples/blob/main/xc7/litex_sata_demo/README.rst is processed through the template in https://github.com/chipsalliance/f4pga-examples/blob/main/docs/templates/example.jinja.
  • However, there seems to be some additional logic involved:
    • In the conf.py module collect_readmes is imported and used: https://github.com/chipsalliance/f4pga-examples/blob/main/docs/conf.py#L86-L98. That's a local Python module: https://github.com/chipsalliance/f4pga-examples/blob/main/docs/collect_readmes.py.

It seems that fill_context from collect_readmes does process the README.rst files in order to generate "contexts" which are then consumed by jinja. Apparently, collect_readmes cannot handle lists, tables or roles.
None of the other example readmes use lists or tables. That's probably why we had not found this problem before.

However, I am unsure about modifying/enhancing collect_readmes being the way to go. Can anyone tell why are we using jinja? If we are executing custom code in the conf.py, we could just copy the readmes to docs/xc7 and docs/eos-s3. Moreover, we could (should) maintain the readmes in the docs subir, not spread along the repo.

@mithro @kgugala @tmichalak wdyt?