Why not Sphinx?

[maximlt]

Which would allow to use the pyodide extension of nbsite (maybe it needs some refactoring) https://github.com/holoviz-dev/nbsite/tree/main/nbsite/pyodide.

I too find MkDocs pretty (prettier than our sites) but we (HoloVIz) use Sphinx + PydData Sphinx Theme and I don't think the difference is big enough between the two systems to push us "maintaining" another docs framework. We're also not an outlier, Pandas for instance uses the same combination of tools to build their site.

Other things we do when it comes to the docs:

• allow to build the docs from notebooks (leveraging MyST-NB, either directly or via the NotebookDirective of nbsite)
• run the notebooks part of the test suite with nbval; Our site builds don't fail when a notebook fails running completely, so this is how we test the site, and usually these are good integration tests too
• probably more!

I had a quick look at this site https://panel-extensions.github.io/panel-precision-slider/. I would have expected to see an app there created when the site is built.

[ahuang11]

I suppose panel-extensions aren’t just for HoloViz maintainers, but for anyone in the community who’s interested in building Panel components. Personally, I think MkDocs is a lot easier to work with compared to Sphinx—it’s simpler to get started, and managing it feels much less complex. It's also a lot prettier as you've mentioned. I don’t think we should let “we’ve always done it this way” hold us back from trying out newer, more modern tools.

The community also shouldn’t have to learn the specific tools we use; they should be able to work with what the broader open-source community is already using and add the necessary extensions to meet their needs. MkDocs was even part of the original copier template for Python open-source projects.

When it comes to functionality, MkDocs seems to check all the boxes:

Pyodide Support: The markdown-exec extension makes it possible to integrate Pyodide directly into MkDocs sites.
Testing: The mktestdocs extension handles testing documentation, similar to what we achieve with nbval.
Notebook Integration: mkdocs-jupyter allows us to embed Jupyter Notebooks, comparable to MyST-NB in Sphinx.

[maximlt]

I suppose panel-extensions aren’t just for HoloViz maintainers

Of course!

I don’t think we should let “we’ve always done it this way” hold us back from trying out newer, more modern tools.

Agree, and I've not said that.

When it comes to functionality, MkDocs seems to check all the boxes:

Pyodide Support: The markdown-exec extension makes it possible to integrate Pyodide directly into MkDocs sites. Testing: The mktestdocs extension handles testing documentation, similar to what we achieve with nbval. Notebook Integration: mkdocs-jupyter allows us to embed Jupyter Notebooks, comparable to MyST-NB in Sphinx.

I'd like to know if we've tried these extensions? If not, this is a problem, and it is why I mentioned Sphinx, because we know it works. Now, if you, as a maintainer of this repo, are very comfortable with setting MkDocs as the default for their Panel extension, then it's fine! But please make sure it works fine for Panel (notebook, pyodide, etc.).

The mktestdocs extension handles testing documentation, similar to what we achieve with nbval.

I think we only use nbval for testing notebooks while mktestdocs focuses on Markdown files and docstrings (still a useful tool).

[ahuang11]

I suppose panel-extensions aren’t just for HoloViz maintainers

Just to be clear, my goal is to make it as easy as possible for community members to document their extensions, and I see mkdocs has a much smaller learning curve compared to sphinx and uses more common tools like markdown for content and CSS for customization.

FWIW markdown-exec is also the maintainer of mkdocstrings

Yes, I can certainly test out the tools and report back. However, even if it doesn't work well, I don't think docs necessarily need to be built with notebooks--using markdown for docs is much cleaner, and less bloated in my opinion.

[philippjfr]

My 2 cents, without going into too much depth here:

• I agree with all the points @ahuang11 makes about MkDocs looking better, being easier to use and customize.
• I think panel-extensions are a good testing ground for trialing a new tool like this for a few reasons. The main one being that the documentation of an extension is much narrower in scope. The API surface of Panel extensions is MUCH smaller than any of our other projects, there's usually a small number of components which can easily be documented, there won't be extensive how-to material, tutorials, reference guides etc. that benefit from running them right there in the docs with the pyodide extension. Even just linking or embedding pyodide based deployments, e.g. with Py.Cafe, Pyscript.com or simple panel convert outputs is likely sufficient to demonstrate the capabilities of a component.

[maximlt]

Your two points seem to contradict each other, if indeed the scope of an extension is much narrower, then I don't see how using Sphinx would be such a complicated thing (specially with LLMs that can help so much these days) :)

Now I also see the interest of trying MkDocs, and if we can get free research by the users of this copier template, why not.

[MarcSkovMadsen]

Here is my take. RUN AWAY FROM SPHINX if you care about user adaption of the template or the extension.

Sphinx is outdated for anything but really technical and scientific documentation. Even the Python doc maintainers are looking for a way out. The alternative to MkDocs is not Sphinx. Its Quarto which has great support for Jupyter notebooks - but its harder to install and more bloated. And Quarto is part of a "competing" ecosystem.

There will be rough edges with MkDocs. But instead of us abandoning MkDocs we should work to get them fixed. And we should build on standards. That would indeed help our users use Panel and HoloViz in their own documentation. I'm pretty sure that no body outside HoloViz setting would use nbsite.

And our Pyodide Sphinx extension needs a modernization anyways. It was a front runner when created. Today it feels slow, bloated and less pretty than what "competitors" have. It does not enable users to edit the code like other frameworks enable their users to do. There is no way to autorun it. I would not use it in my own projects to be honest.

I see panel-extensions as an opportunity to experiment and modernize. Here we can give our things a modern look and feel. Not being hold back by the existing HoloViz tools and infrastructure. Then bring modernization back into Panel and rest of HoloViz ecosystem.

[maximlt]

Obviously, you all prefer MkDocs, so be it :) In some other setups, creating a copier package like this one would have started with a design doc, explaining why each tool is chosen with a comparative analysis between tools. In our OSS way, we take shortcuts as we don't have time to go through these longer processes. I see that Marc opened a similar question about uv vs pixi, so I think the question I asked wasn't unreasonable, and there's no need to write in uppercase letters to make a point...

My main thing was not to challenge MkDocs as a framework to build docs, as far as I can see it's a fine one (as Quarto, mystmd, and the many other static site generators that are prevalent in other ecosystems). I'd love if we could support them all! What I questioned was the decision to make it the default docs framework of this copier, as I imagined that some users (copier users, or visitors of an extension site) would ask for the features we have on the Panel site like the pyodide extension (Jim, typically). Some of them may also want to have their site look like the "official" Panel site. You can now point them to this issue where they'll the reasoning behind that decision. And the good news is, no one is forced to use MkDocs in the end :)

---

@MarcSkovMadsen I want to ask you some more questions as your intention seems not to just MkDocs here but ultimately update all the other HoloViz tools.

if you care about user adaption of the template or the extension

Do you have evidence showing that adopting the Pydata Sphinx Theme hinders the adoption of our HoloViz tools?

Sphinx is outdated for anything but really technical and scientific documentation.

Why outdated? I'm also unsure whether you're talking about Sphinx or the PyData Sphinx Theme. Sphinx with the Furo Theme is used, for example, by attrs or black. Can you please precise your thoughts?

Even the Python doc maintainers are looking for a way out.

Do you have a link to share about that? I remember reading somewhere about moving the Python site to Furo.

And we should build on standards.

Can you precise what standards you refer to?

[MarcSkovMadsen]

Look and feel is personal.

For me this example https://awesome-panel.github.io/panel-copy-paste/ makes it very clear to me how much better MkDocs is for developers and for users.

• It looks better
• It was so much easier to find what I needed in the MkDocs as a newcomer as in Sphinx docs as an experienced Sphinx user.
• The mkdocs-pycafe extension is much more powerful than our pyodide sphinx plugin.
• The reference documentation can actually be read.
• Try the search function. Don't think I have to say anything.
• .. and much more.

The one downside right now is that we don't have pre-rendered pages. Either we embed live via py.cafe, we provide a link to py.cafe, we embed a picture or video, or we figure out how to include pre-rendered stuff.

[ahuang11]

The correct link is https://awesome-panel.github.io/panel-copy-paste/

[philippjfr]

The main point I'd make about the adoption of MkDocs without previous in-depth discussion is that in OSS those who do the work get to make the decisions. That becomes less true for well established projects of course but the way I see it Panel extensions are novel ground.

They are also an effort to catch up to the extensive ecosystem built by other communities so we should aim to make it as modern and user friendly as possible and as far as I can tell MkDocs is that.

That's also why I don't think my points above are contradictory at all. Panel extensions docs will never be as extensive as those of one of our other projects but even for a small project Sphinx+nbsite configuration can be super confusing as soon as you want to do something even slightly non-standard and we still have no way to generate even mildly acceptable API docs, which means it doesn't even help the user with the most basic function. Also, as far as I can tell there is no LLM or documentation out there that can answer even fairly basic questions about Sphinx.

HoloViz as a whole has a lot of legacy code, docs, infrastructure etc. to handle and while standardization is nice I think it's also dangerous and leads to staleness and complacency. If we can use extension packages as a playground for new ideas that's a great thing.

I think the decision to adopt pixi highlights the need for more risk taking and experimentation. I'm still not sure if pixi will win out or was the absolutely best choice for our projects but I do know that I am very grateful to @hoxbro for putting in the work and getting us out of the dead end that was pyctdev.

I also think discussion like this is a good thing and keeps everyone accountable.

[MarcSkovMadsen]

A comment about pixi. I realized that it works great for ci/cd. But I/ we need to figure out how to make it work better for local development.

I'm also totally grateful for migration to pixi as now there is transparency and traceability.

[maximlt]

The main point I'd make about the adoption of MkDocs without previous in-depth discussion is that in OSS those who do the work get to make the decisions.

I agree and that's how I usually approach reviewing PRs. It's also worth noting that the people making the changes aren't necessarily the only maintainers of the new state in the long run (speaking of experience with having had to touch pyctdev and nbsite).

---

The discussion becomes a bit hard to follow as it's mixing up talking (1) about this template, (2) about docs in the whole HoloViz ecosystem, and (3) pixi.

On (1), I still think that it would also have been possible to come up with a default setting for Sphinx that provides a decent user experience to build these narrowly-scoped extension docs (the whole purpose of a template is to provide reasonable default settings). I understand you all want to experiment with MkDocs, which is obviously fine!

Also, as far as I can tell there is no LLM or documentation out there that can answer even fairly basic questions about Sphinx.

I've used ChatGPT a fair bit to help me write Sphinx extensions recently, it made a big difference!

On (2), I would not compare the situation we had with pyctdev (custom and unmaintained project workflow tool with a too large scope) to what we have with Sphinx (actively maintained and used by thousands and thousands of active projects, in particular in the ecosystem familiar to our users) or the PyData Sphinx Theme (actively developed, recent work on accessibility). I'm more concerned about MyST-NB which is in a maintenance state as efforts of this group seem to have been redirected to the development of mystmd. In any case, migrating to another static site generator is going to be a big task (it'd be nice to estimate how many hours) and needs to be well motivated IMHO. I'm not yet convinced by the arguments that were brought up and there are rough edges indeed with MkDocs (this looks like a blocker no?):

The one downside right now is that we don't have pre-rendered pages. Either we embed live via py.cafe, we provide a link to py.cafe, we embed a picture or video, or we figure out how to include pre-rendered stuff.

@MarcSkovMadsen you may want to open a separate issue to discuss this in more depth https://github.com/holoviz/holoviz/issues, this may end up in a HEP (the transition to pixi could also have been a HEP).

On (3), agreeing with everything that was said :)

[ahuang11]

It would be an interesting experiment to create a mkdocs.yml in the panel repo with either pre-built docs or the notebook extension, and run mkdocs serve to see what it would look like without putting in much effort.

If the search is much better, I think that is already a big motivator to migrate, and after, move this discussion to Panel issues instead.

Edit: okay it seems like some effort has to be put in due to the markers in {}

INFO    -  Doc file 'api/config.md' contains an unrecognized relative link 'cheatsheet#pn-extension', it was left as is. Did you mean 'cheatsheet.md#pn-extension'?
ERROR   -  mkdocstrings: No module named '{admonition} Note'
ERROR   -  Error reading page 'developer_guide/index.md':
ERROR   -  Could not collect '{admonition} Note'

[maximlt]

Can MkDocs read MyST Markdown files?

If the search is much better, I think that is already a big motivator to migrate

Yep the search we have is pretty bad. Has anyone looked into fixing it? Or alternatives like hooking up Algolia?