pallets
Move current docs to myst
Move any sections of the docs to myst using rst-myst command line tool.
- Make the PR from stable
- Install rst2myst with uvx since its requirements are not up to date so it will downgrade your sphinx if you install it in the project environment.
- Use to convert 1 file (for example contrib.rst)
- Fix typos.
- Make PR for that 1 file. If you are planing on helping out will multiple sections, then submit 1 or 2, and I will review them and then you can do more. Because the rst2myst does make mistakes, the reviewer(probably me) needs to click on every link and check carefully line by line.
Just add a comment to what section you are working on.
An unfortunate downside is that the git blame will be reset for the docs files.
The index.rst file needs to be the last file converted since I cannot figure out to have rst files and a md file as the index. See myst docs for how to use myst with sphinx roles. We have a custom roles that will need eval-rst. Check other docs already created for examples and click-extra docs for how the roles work.
I did a PR for the Why document. #2949 I can work reverse alphabetical as the PRs are accepted. Next would be wincmd.rst then virtualenv.rst and so on.
@Veebaa we already have two people working on this, as shown by the issue assignment and many linked PRs. Please hold off unless @Rowlando13 says otherwise. See https://palletsprojects.com/contributing/
I am going to start working on documentation.rst, let me know if anyone else is working on it.
@Veebaa let's get your first PR successfully merged before you start another.
@Rowlando13 Sorry, I just saw your message there now. I did a new PR for the contrib document, and have also done a PR for documentation doc.
Let me know if you are happy for me to carry on with some more now 😄
@Veebaa No problem. You are good to keep going; let's just do one at a time.
Hey @Rowlando13, FYI, I just added support of MyST syntax for the click:example and click:run Sphinx directives.
With that you can use natural MyST syntax like:
```{click:run}
invoke(hello_world, args=["--name", "Joe"])
```
Instead of the ugly:
```{eval-rst}
.. click:run::
invoke(hello_world, args=["--name", "Joe"])
```
It will be available in the upcoming Click Extra 5.1.0 (which is pending Click 8.2.2 release).
Hey @Rowlando13, FYI, I just added support of MyST syntax for the
click:exampleandclick:runSphinx directives.With that you can use natural MyST syntax like:
invoke(hello_world, args=["--name", "Joe"])Instead of the ugly:
.. click:run:: invoke(hello_world, args=["--name", "Joe"])It will be available in the upcoming Click Extra 5.1.0 (which is pending Click 8.2.2 release).
To use click-extra would require adding it to the imported extensions but there might be an issue with doing that. @davidism will know. I will keep using the eval-rst method for now.
https://github.com/pallets/click/blob/c096a10e8b59e48f77c65372a9c17f8226c128c5/docs/conf.py#L15-L23
@denuoweb we already use click-extra for generating docs so nothing new to add.
To use click-extra would require adding it to the imported extensions but there might be an issue with doing that. @davidism will know. I will keep using the eval-rst method for now.
Yes I think you should keep using the safest option, which is {eval-rst} for now.
Click Extra is my playground where I can push the limits of Click and its ecosystem, and move fast and break things. I was just pointing out to my latest progress for inspiration.
@denuoweb we already use click-extra for generating docs so nothing new to add.
Hmm. I don't think you are using click-extra. Do you? I can't find any reference anywhere... You are currently relying on pallets_sphinx_themes only right?
I was definitely wrong there. Looks like we get the Sphinx role from the pallets theme. Out of curiosity, did you get the role from the theme or did it get the role from you.
I was definitely wrong there. Looks like we get the Sphinx role from the pallets theme. Out of curiosity, did you get the role from the theme or did it get the role from you.
I was initially relying on pallets_sphinx_themes's directives to document Click Extra, like Click does.
Then I patched them in Click Extra to support ANSI colors for rendering .. click:run:: directives.
And this week I completely forked and refactored pallets_sphinx_themes code into Click Extra to support MyST directives.
And for the full history of that feature, a couple of years ago I proposed to move the .. click:example:: and .. click:run:: roles implementation from pallets_sphinx_themes's to sphinx-click.
After reading how its split up, it is a bit awkward and not ideal. I might have solution but it would be multistep.
- The
pallets_sphinx_themeimpacts all of pallets so I can understand not wanting to depend on sphinx-click. However, maybe we can take those roles out of theme since they really just belong to click. - 'sphinx-click` does not really want them in 2 places, so he probably won't take them unless we move them out.
- You are the one who has done the work so the roles are currently in
click-extra.
Maybe see if we can see if the sphix-click maintainer would be amenable to moving to pallets-eco?
Less maintenance burden for them since we update the standard pallets toolchain. Reliability of update for click maintainer since I think the pallets team has access to release. Moving it there would also allow us decouple the pallets theme from click only stuff. And then I could merge stuff for you as needed. I also think that sphinx themes are hard to maintain so might be nice to move stuff out of there.
Thoughts @kdeldycke @davidism ?