Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Using the html repr in the documentation #6620

Closed
OriolAbril opened this issue May 18, 2022 · 2 comments
Closed

Using the html repr in the documentation #6620

OriolAbril opened this issue May 18, 2022 · 2 comments

Comments

@OriolAbril
Copy link
Contributor

What is your issue?

most (if not all) of xarray documentation is written as rst files and using the ipython directive. Due to this, the html repr is not use in the documentation. I find the html repr to be much more informative and intuitive, especially for beginners and I think it would be great to use it in the documentation. There are multiple ways to do this (not necessarly incompatible between them):

  • Use jupyter sphinx instead of ipython to run and embed code cells from rst files. I use this in the documentation of xarray-einstats for example
  • Use jupyter notebooks instead of rst. We use this in arviz and xarray-einstats docs. However, in order to keep using all the sphinx roles and directives used the sphinx configuration would need to be modified to use myst-nb instead of nbsphinx
  • Use myst notebooks instead or rst. Also used in ArviZ, also needs myst-nb instead of nbsphinx.

afaik, nbsphinx can be changed with myst-nb without needing to do any changes to the documentation, then rst files could be progressively updated to ipynb, myst or any other format supported by jupytext, rst, markdown and notebook sources can all be used at the same time to generate the documentation and link from one to the other with sphinx roles and cross references.

Is this something that sounds interesting? I could update the infrastructure at some point whenever I have time and update a page (to any or multiple of the options above) as an example and then let other people take over

@OriolAbril OriolAbril added the needs triage Issue that has not been reviewed by xarray team member label May 18, 2022
@dcherian dcherian added topic-documentation and removed needs triage Issue that has not been reviewed by xarray team member labels May 18, 2022
@TomNicholas
Copy link
Member

I think this would be really nice, but would defer to others' opinion on the best way to implement it.

@dcherian
Copy link
Contributor

dupe of #3893 and #7924

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

No branches or pull requests

3 participants