Be consistent in our use of markup languages in examples

[12rambau]

I already raised this concern earlier last year, we are not consistent in how we show examples and how we create documentation pages in our documentation. I think it is now leading to usage issues with our newest users (#1365).

I know that @choldgraf is a very strong advocate of mystnb, I'm not. This issue was about the way we write the documentation and the conclusion was anyone with the will to write down a page should be able to do it either in .rst or .md as we use the mystnb extention.

Now I would like to focus on the examples as people may not use mystnb in their doc. Could we show them by default in what sphinx is using e.g. .rst and optionally show how it looks in .md ?

[choldgraf]

Let's separate out mystnb, which is about using jupyter notebooks in sphinx, from myst, which let's you write markdown in sphinx. I think you're talking about the latter, yes?

My feeling is that we should understand who our users are and what they want to write and base our examples around this. My bias is certainly towards markdown in this regard: I find that more people find it more accessible and enjoyable to write. I think it's a safer entry point into sphinx than rST since many people are already familiar with markdown.

But that's an empirical question. I wonder if we could ask around in the projects that use our theme and ask them:

1. What markup language they use in their docs?
2. What markup language they would prefer to use if they were starting from scratch?

And use that to try and drive a decision here.

[trallard]

I am certainly biased towards markdown too - it is way more accessible and even after many many many years writing rst files I have to check the syntax every time.

While it would be nice to survey our users to get a better feel for what markup they prefer and use, I fear that by only having examples in one or another would alienate the ones using the other markup.

Perhaps the alternative (though would require effort on our end), would be to present both markups using the tab (think that is the name) component?

Edit: yes that is the name https://pydata-sphinx-theme.readthedocs.io/en/latest/user_guide/web-components.html#tabs

[12rambau]

this is exactly what I was thinking about, we could mimic what they are doing in sphinx-design: https://sphinx-design.readthedocs.io/en/latest/grids.html

[drammock]

showing examples in both formats is the right solution IMO. The tab component seems like the obvious choice too. Now who volunteers to do it? 🙈 or can it be automated?

[choldgraf]

I'm all for it as well...though I share @drammock's concern about maintainability. I'd be +1 on just slowly implementing it page-by-page.

[trallard]

Yep I anticipate it will require a big initial effort and subsequent maintenance.
We could do it page by page - and if we organise a certain way to track the changes it could also be a good way to signal newcomers friendly issues for any potential contributors?

By organising I mean - nothing fancy but an issue with a checklist where we can track which docs have been updated. WDYT?

[drammock]

+1 for a checklist issue that identifies all the places it's needed, and tagging it as good first issue