Retype with MyST MyST-NB Jupytext and Multi Repo Sourcing

[atraining]

Hi @geoffreymcgill ,

is there any documentation how Retype can work for

1. multi repo documentation setup: Multiple repos cotain a docs folder but we want to unify those documentations in a single static page - comparable with https://antora.org/
2. rendering jupyter: here is a demosetup - https://github.com/atraining/python-tutorials results in https://atraining.github.io/python-tutorials/tutorials/addition/index.html

Best

Chris

[geoffreymcgill]

1. multi repo documentation setup: Multiple repos cotain a docs folder but we want to unify those documentations in a single static page - comparable with https://antora.org/

This is functionality that I've been thinking a lot about recently. I too have a scenario where I would like to pull or combine documentation and code samples from several different repos. At the moment, I don't have a good solution, other combine the files into a monorepo repo, which could be automated.

Calling out to other repos or combining files from multiple repos into one virtual directory also kinda goes against one of the main directives of Retype, and that is to not make external calls.

The Code Snippet component does have the ability to reach outside of the project file structure, although those files would still have to be located on the local file system. This would work fine if you had both repos cloned locally and were running retype build locally, but it would not work if you were using the GitHub Action to build as part of your CI process.

2. rendering jupyter: here is a demosetup - https://github.com/atraining/python-tutorials results in https://atraining.github.io/python-tutorials/tutorials/addition/index.html

Can you provide a specific sample of what you would like to render in Retype?

Are you asking if Retype can generate a website from a Jupyter Notebook? or convert into Markdown files? Unfortunately, the answer to both those questions would be no.

[atraining]

Hi @geoffreymcgill,

thanks for your fast response and your detailed thoughts.

Concerning 1: We were thinking to create a monorepo using Github Actions that pulls the docs folder from multiple repositories to then build the static page. Concerning 2: Thanks for the answer. Just to add one note here, the github repo I provided does show how a markdown file is executed before the static site is build. This allows to execute code blocks included in markdown via myst-nb and jupytext to then include it as an HTML file in the static page: https://[raw.githubusercontent.com/atraining/python-tutorials/gh-pages/_sources/tutorials/nan-values/index.md](https://raw.githubusercontent.com/atraining/python-tutorials/gh-pages/_sources/tutorials/nan-values/index.md) - So I just wanted to add this workflow as an example. I am aware that retypeapp would not be made to do this out of the standard.

Feel free to close this issue if you think it's not really a "ticket" but was rather a discussion.

Thanks for this one :)

Best

Chris

[geoffreymcgill]

Concerning 1: We were thinking to create a monorepo using Github Actions that pulls the docs folder from multiple repositories to then build the static page.

Yes, this is the approach I'm going to take first as well. It should work well and provides unlimited flexibility. If I get a solution working cleanly, I will publish the details and share the update in this thread.

This allows to execute code blocks included in markdown via myst-nb and jupytext to then include it as an HTML file in the static page:

It's nice functionality. At some point in the future, I would love to build this into Retype.

For future reference, here's the snippet of Markdown and final generated result:

## Addition of two numbers

The easy way:

```{code-cell}
def add(x, y):
    return x + y
```

```{code-cell}
add(1, 1)
```