Hello!

[astrojuanlu]

Hi! It's Juan Luis from Read the Docs here 👋🏽 Just found this project by chance, I was surprised to see interest from the R community to host their projects on RTD! Opening this issue just so say hi and reach out in case RTD can help in any way.

I see you already did the migration from recommonmark to MyST. Not sure how easy it is to convert from Rmd to MyST but surely it's easier than converting to reStructuredText, I suppose :)

[mpadge]

Hi @astrojuanlu, thanks so much for reaching out!! One strong motivation for his project is because (as said on the README), the entire R ecosystem is so focussed on single packages, which makes it virtually impossible to use any current doc system for anything more complex or different. I want to open up more opportunities here. Plus both rST and MySt are so much more powerful than the pretty vanilla markdown mostly used in R, but .Rmd is so dominant that is effectively suppresses awareness of the way more expressive capabilities of these other markdown forms.

What I might do is to leave this issue open an use it to ping you here with any questions i have. You'd be very welcome to contribute here in any way, including ideas, design, whatever. There aren't too many technical issues to solve to get this working (#5 is an example), but quite a few design issues. One of the biggest of those is one which I would really appreciate some core-RTD insights into, which is the "conflict" between README.md and docs/index.(rst/md):

• R packages are effectively obliged to have extensive README.md files which R-internal doc systems use to render as main landing pages.
• R has very well developed systems for .md generation, so easiest option would be to use RTD to convert README.md into docs/index.md, but ...
• README files for R packages are often very long, and toctrees then get (auto-)inserted and effectively lost way at the end.
• My current solution is to skim other meta-data to make a skeleton docs/index.(rst/md) with a single-sentence description and auto-generated toctree which includes an initial "Introduction" section linking directly to docs/README.md.
• Original and full README files can then very easily be re-embedded with a single insertion of child doc into index.(rst/md).

Any advice here? Are there any examples of current RTD "best practices" in this regard?

[astrojuanlu]

What I might do is to leave this issue open an use it to ping you here with any questions i have.

That sounds perfect! 💪🏽

One of the biggest of those is one which I would really appreciate some core-RTD insights into, which is the "conflict" between README.md and docs/index.(rst/md):

This is what I'm doing now in my projects:

$ cat docs/source/index.md
% Include the README contents here!

```{include} ../../README.md
:relative-images:
```

% Extra content goes below

Check out {doc}`/usage` for further information,
and {ref}`Installation` for installation instructions.

```{warning}
This library is under active development.
```

```{toctree}
:caption: 'Contents:'
:maxdepth: 2

usage
notebooks/tutorial
```

(source: https://github.com/readthedocs/tutorial-sphinx-markdown-library/blob/tutorial-steps/docs/source/index.md)

That way, I reuse the README.md in the index page of the docs, and then optionally I add some extra content. What do you think?

[mpadge]

Thanks @astrojuanlu - the issue here is that I think it will generally be best NOT to reuse README.md contents in the index page. Maybe what I could do is expose a binary parameter, include_readme or readme_in_index or something to let people decide for themselves. If TRUE, then the index will just be README + toctree; if FALSE, then a dummy template extracted from package metadata. That should work well - thanks!