-
Notifications
You must be signed in to change notification settings - Fork 307
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
drop .md pages in our own documentation #1475
Comments
The extra dependency / release cycle is indeed a big pain point for me. The latter point I think is not quite right --- it's not users who need to learn MyST in order to use PST. Rather it's contributors who need to learn it in order to contribute. Still a problem though. I'll skip the points about MyST being "messy" and "difficult" (I don't disagree, but I can see how someone might). But the "non-reusable" point just bit me last week; I strongly agree that a Sphinx theme that supports rST should not have a custom directive that only works for MyST source files. If we're going to support both rST and MyST, any custom stuff we add to Sphinx should ideally support both rST and MyST, but if it only supports one it should be rST. Just to explicitly separate the issues:
My vote is:
|
My 2 cents as a user. Would The site I'm working on (a French LaTeX FAQ) will use only (
|
The current It seems possible to implement the directive using nodes, or to auto-detect the containing file's type and adjust, but I agree with you that simplification to reST is probably the best approach. A |
@dbitouze we will remain compatible with I checked your documentation and you are not using any of the advanced directive structure of |
@AA-Turner I would prefer to go down the node approach, I'll check the sphinx-design documentation and API to see how they implemented grids. |
At a glance, you'd probably need to instantiate a |
Do you mean the user will decide to see only
I'm using Emacs 😉, which has a (not very powerful)
Sorry, I don't what you mean.
Which advanced directive structure of |
@dbitouze I think you missed the point of this thread. The documentation you are writing is using the
With |
OK, sorry for the noise, then. But, just to be sure, will the theme documentation still expose both
At least the following does work: Foo
: bar:
- baz
```
Test
``` but...
... maybe, indeed, I completely missed the point of this thread. In such a case, sorry again for the noise. |
ah, you're correct. That simplifies things. So if we switch all our doc source files to |
Wearing a maintainer hat: I am ok with either all of our PST (Pydata Sohunx Theme) docs being on As a PST user and reinforcing the points made above by other users, it is important that we keep providing support for end-users to write in whichever markup language suits them best,
I thought this was a point we had agreed on before. All our examples show both syntax examples. Now onto this point:
If we indeed have any custom directives that are |
I think you nailed it @trallard. I do think that having all of PST doc files in
Agreed, this seems like the right approach (given that the custom directive was internal to our docs, not something users could have been using in their own sites --- we are free to change it at will). |
For what it's worth, I definitely don't like writing rst, but if others are aligned on the need to remove MyST from the pst docs, I won't object. |
My request is actually the reverse of #639
The conclusion of #639 was "come as you are". I was liking it at the time but I'm not liking it anymore.
My rational is that we are a
Sphinx
based theme, our goal is to extend as much as we can whatSphinx
does and make it better, not promoting new tool (even when they are great as Jupyterbooks ormyst
).Why ? because then not only we are making ourselves bound to their releases processes but more importantly we are forcing users to not only learn sphinx and rst but also learn all this extra-lib that they may not know/need.
myst
in itself is parsing .md files to .rst before sending them to theSphinx
builder. It's great and it will work without any changes from our side so why not stick to the .rst way ?I know that many of you are big users of jupyterBooks so you are more used to
myst
than I am and you feel it's easier.I still think that there are more people like me than like you as this theme can be used for things that are 100% unrelated to Jupyter. Even though I understand that for simple text documentation it's just fine and I agree that .rst can be a bit convoluted sometimes but whenever you try to do more complicated things it becomes:
Note that I would happily do as in sphinx-design where they decided to promote myst by showing for every commands the 2 writting options: https://sphinx-design.readthedocs.io/en/latest/grids.html but my suggestion here is to harmonize the writting of our docs to allow new users to participate without enforcing a new markup language.
The text was updated successfully, but these errors were encountered: