Mrc 5033 Autocode execution

[M-Kusumgar]

run hatch run generate-docs and then open the docs/_build/index.html file to view docs

[M-Kusumgar]

okay I think I maybe be cooking with this one potentially, had to dig through the source code to find that # ignore but we might be able to do the setup without showing it to the user, let me know what you guys think

[r-ash]

Looks like this is going to be quite limited in terms of what code blocks we can include.

Looks like no persistent data between separate code blocks. With something like

```{runblock} pycon
>>> exec(open("./docs/setup/helper.py").read()) # ignore
>>> x = multiply(1, 2)
```

```{runblock} pycon
>>> print(x)
```

We get an error in generated docs

Traceback (most recent call last):
  File "<input>", line 1, in <module>
NameError: name 'x' is not defined

Which is going to be a real pain for writing any long form vignette like docs. Have you seen https://machow.github.io/quartodoc/get-started/overview.html looks like it is made to be very similar to R in docs it produces. There is an example here of the docs site it creates https://rstudio.github.io/pins-python/

But I also wonder if there is a better way to do this with Sphinx? Do you know what numpy or pandas are using for their docs? It says it is built using sphinx but they must be doing something to have persistent code blocks in e.g. https://pandas.pydata.org/docs/user_guide/10min.html

[richfitz]

Looks like the numpy docs are using something based on ipython notebooks to me (jupyter notebooks). some pointers to other ideas here : quarto-dev/quarto-cli#2638