[docs] Add support for external markdown#23505
Conversation
| GitHub: | ||
|
|
||
| ```html | ||
| <!--$UNCOMMENTthis will be uncommented--> More text |
There was a problem hiding this comment.
I wonder if we can somehow make this convention easier in a follow-up PR. It'd be great to add more external content from trusted sources, without them having to add our special commenting syntax.
maxpumperla
left a comment
There was a problem hiding this comment.
Fantastic idea, really like the preprocessor system!
| @@ -0,0 +1,8 @@ | |||
| <!-- | |||
There was a problem hiding this comment.
do we need one for xgboost as well?
There was a problem hiding this comment.
There is a file there for xgboost already
|
@amogkam I'll add a convenience script to convert an external markdown file to MyST file and then you can build the docs locally with that included to see how it will look like |
krfricke
left a comment
There was a problem hiding this comment.
Great idea! And I generally like the implementation. Just two questions:
- Instead of uncommenting e.g. headlines, can we just have a "template" on the Ray docs side that replaces some body part with the fetched content? That way we can have more content on Ray (e.g. the API docs, which are not used in the library READMEs at all but only in the Ray docs).
- Can we just convert the READMEs with some converter instead of providing e.g. two versions of the same table?
|
@krfricke The problem with conversion is that there are some elements that only make sense in the docs (eg. sphinx headers). As for the tables specifically, I believe there wouldn't be any issues if we left them in markdown, this is just how it is in the docs currently. I toyed with the template idea before through the use of sphinx directives, but unfortunately it's not straightforward (especially with MyST having issues with custom Include-like directives). I think the simple uncomment/remove combo provides the greatest flexibility. Templates etc. could potentially get messy and complicated. Plus we are in control of the external docs, so we can make any changes we need anytime. |
Adjust the readme file to take advantage of ray-project/ray#23505
Automatically pull the latest ray_lightning README to render on Ray docs. (#23505) Depends on ray-project/ray_lightning#135
Why are these changes needed?
This PR fixes the issue of diverging documentation between Ray Docs and ecosystem library readmes which live in separate repos (eg. xgboost_ray). This is achieved by adding an extra step before the docs build process starts that downloads the readmes of specified ecosystem libraries from their GitHub repositories. The files are then preprocessed by a very simple parser to allow for differences between GitHub and Docs markdowns.
In summary, this makes the markdown files in ecosystem library repositories single sources of truth and removes the need to manually keep the doc pages up to date, all the while allowing for differences between what's rendered on GitHub and in the Docs.
See ray-project/xgboost_ray#204 & https://ray--23505.org.readthedocs.build/en/23505/ray-more-libs/xgboost-ray.html for an example.
Needs ray-project/xgboost_ray#204 and ray-project/lightgbm_ray#30 to be merged first.
Related issue number
Checks
scripts/format.shto lint the changes in this PR.