Update Theme to be able to update mkdocs in OI repo

[Toasterson]

@JMadgwick In the monthly maintainer meetup the age of our mkdocs package in oi-userland came up. I see we are using GitHub Actions so it wouldn't impact the docs directly if we update now but I also saw #220 so we would need to update the theme to make be able to update our mkdocs for docs. I think we should start of working on these things, so we can keep up to date with the docs pages. Whats your opinion?

@cstes here the reference issue

[drscream]

Would changing to a modern theme (like the Material for MkDocs) being an option. It would still require additional work to review and fix issues, but the theme would provide existing Markdown features for the notes part for example.

I asking before working on the integration of a new theme.

[Toasterson]

I am tempted to say yes, as there is also Spacelab and Solar available. So we have some more thourough designed art and colorspace options that are pleasing on the eye. It depends if we want to keep the colorscheme we have now. If not I my vote goes towards a new theme. And I am not fond of our current coloscheme.

[JMadgwick]

The primary problem with #220 was the formatting elements for the "notes" and "warning" section were not supported and these sections weren't displayed at all. There were some other parts of the site which has similar problems.

This isn't to say that MkDocs can't or shouldn't be upgraded. If there's a different theme which supports the formatting element we use then that seems like a good solution.

[drscream]

I would rewrite the notes part to match the required style for the mkdocs markdown extension used by the theme.

I will work on that during the weekend and prepare a testing branch for you all.

[cstes]

Maybe the expression"update mkdocs" is a little misleading here. All that is needed is to repackage or rebuild (update) the IPS package for mkdocs. The version can remain 1.0.4 but the IPS package should be rebuilt with python 3 instead of python 2.7.

The Illumos issue is

I occasionely use the IPS mkdocs package on OpenIndiana as the documentation website explains that also other platforms such as Linux can be used to author documentation content : see

So I think it is possible to stay / stick with mkdocs 1.0.4 and simply adapt / rebuild for a newer python version.

[cstes]

Also the IPS mkdocs package itself could simply be removed from the IPS repository as it is not so difficult to simply follow the "http://docs.openindiana.org/contrib/getting-started/" instructions using "pip install" instead of "pkg install" for mkdocs.

[drscream]

I think it would anyway make sense to update the documentation to use the latest mkdocs version maybe with a more modern theme. So they are two different issues:

• one to remove mkdocs from oi-userland (or update it), which might be created on oi-userland repo?
• one to keep the mkdocs updates for the documentation itself?

[JMadgwick]

My understanding is the same as @cstes. It makes sense to update the IPS package to a newer version, but this is unrelated to Python 2 removal, as the existing version doesn't require it. This is also unrelated to this repo. Personally, I also don't see why pip packages should be part of the IPS repository at all if they can be installed using pip in OI - what benefit does this provide vs the associated maintenance cost.

None of this detracts from the benefits of upgrading the docs to use a newer MkDocs and a better theme. I'm unsure if MkDocs material is the right theme for this though as it has a problem with the PDFs (see PR comments). I'll have a look at some other themes to see if we can avoid the problems with MkDocs Material.

[Toasterson]

For the userland package my vote goes towards using pip and updating the documentation. Best we open a ticket on the issue tracker in the opeindiana project. It is what was used for a long time. I see @cstes already did that :) https://www.illumos.org/issues/14791

For the theme upgrade I am curious if the Solar or Spacelab theme also have that problem?

[JMadgwick]

It is an easier migration if the spacelab theme is continued. The changes required are quite simple, I described them in this comment on the PR. With a few other style tweaks it is possible to retain much the same look and feel as the current docs site. The only difference is a slightly larger font size.

The MkDocs Material PR is now passing and the PDF issues are resolved. It will be up for the community to decide if they wish to move to it. Overall the feel of MkDocs Material is more modern, but I'm not sure if that's what we want for OI. The navigation doesn't use drop downs which is a change compared to the current docs.

[Toasterson]

If people are happy with the look of Material I am not against it. Especially if it fills all features.

[JMadgwick]

Well, it's been a while since the last activity here and nobody has said they don't want the Material theme.

The mkdocs version we are using is now even older (not working with latest Python) and so the need to upgrade is more urgent. I've made some updates to the PR attached to this issue and fixed some minor residual problems it had. So far as I can tell, everything is working as it should now. Any comments? Should we merge now?

[cstes]

I think mkdocs was updated together with major work on python updates in the OpenIndiana repository. There is a mkdocs, a mkdocs-37 and a mkdocs-39 package.

library/python/mkdocs@1.5.2,5.11-2023.0.0.0:20230804T073656Z
library/python/mkdocs-37@1.4.3,5.11-2023.0.0.1:20230804T073718Z
library/python/mkdocs-39@1.5.2,5.11-2023.0.0.0:20230804T073636Z

I know nothing about mkdocs and themes, but I can test the update if you merge the PR to change or update the Mkdocs theme to a new theme.

[JMadgwick]

@cstes There's likely also a need for mkdocs-material to be packaged. Though I think all of this should be installable from pip in any case.