Sphinx Docs Starter Pack does not work on non-Ubuntu Operating Systems

[dviererbe]

I was approached today that the make file does not work on mac and that there are other non-Ubuntu users who want to work with the starter pack.

The particular issue that failed the make file was my recent change #226, because on mac there is no apt-get command and no distro-info package.

I would like to raise the question with you here: Are non-Ubuntu systems supported?

If the answer is yes:

1. this should either be considered for the development of the new sphinx plugin,
2. or we provide instructions how to emulate Ubuntu (e.g. with lxd, multipass, wsl, qemu) to work in an Ubuntu environment on non-Ubuntu host systems with the starter pack.

[dviererbe]

In the meantime, here is a work around (not a long term solution!) to remove the dependency on apt-get and distro-info:

diff --git a/Makefile.sp b/Makefile.sp
index b85f6b4..8bf1321 100644
--- a/Makefile.sp
+++ b/Makefile.sp
@@ -51,8 +51,6 @@ sp-pa11y-install:
                }

 sp-install: $(VENVDIR)
-       sudo apt-get update
-       sudo apt-get install --assume-yes distro-info

 sp-run: sp-install
        . $(VENV); sphinx-autobuild -b dirhtml "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS)
diff --git a/conf.py b/conf.py
index 16f8522..ca667d5 100644
--- a/conf.py
+++ b/conf.py
@@ -112,8 +112,7 @@ if 'custom_rst_epilog' in locals():
 if 'custom_manpages_url' in locals():
     manpages_url = custom_manpages_url
 else:
-    manpages_distribution = subprocess.check_output("distro-info --stable", 
-                                                text=True, shell=True).strip()
+    manpages_distribution = "noble"
     manpages_url = ("https://manpages.ubuntu.com/manpages/"
                     f"{manpages_distribution}/en/"
                     "man{section}/{page}.{section}.html")

[dviererbe]

Ideas for a long term solution that does not depend on apt-get for the above mentioned problem:

1. download and parse https://git.launchpad.net/ubuntu/+source/distro-info-data/plain/ubuntu.csv directly (effectively implementing distro-info --stable ourselves)
2. there is a python3-distro-info package (see https://launchpad.net/ubuntu/+source/distro-info) which contains a python module that could be used in the python script directly, but it is not in the pip store, so we could look into publishing this module there and adding it to the requirements.txt file

This could also be a solution for #231

[dviererbe]

cc: @ru-fu @tigarmo

[evildmp]

Unfortunately #226 needs to be reverted - the starter pack must be usable on non-Ubuntu systems. All Unix-like systems within reason should be supported (other Linuxes, macOS).

[AnneCYH]

Unfortunately #226 needs to be reverted - the starter pack must be usable on non-Ubuntu systems. All Unix-like systems within reason should be supported (other Linuxes, macOS).

Hi @evildmp , would the workaround suggested here be acceptable for now? Instead of completely reverting the PR. https://github.com/canonical/sphinx-docs-starter-pack/issues/232#issuecomment-2126650323

Thanks!

[dimaqq]

How about running the commands in a container, as a work-around?

[ru-fu]

I have the feeling we're overengineering this a LOT.

First question: How many projects does that actually affect? I personally didn't even know about the :manpage: role before https://github.com/canonical/sphinx-docs-starter-pack/issues/224 was raised. I'm not saying this isn't a useful role, but if this affects one or two of our doc projects only, the solution can be added to custom_conf.py and doesn't need to go into the starter pack at all.

And if we want it in the starter pack, I think it would actually be better to have a version variable in the configuration. I could imagine doc sets that are released in different versions for different releases, so they would need custom URLs anyway.

[ru-fu]

Unfortunately #226 needs to be reverted - the starter pack must be usable on non-Ubuntu systems. All Unix-like systems within reason should be supported (other Linuxes, macOS).

To clarify: The basic functionality (building and previewing documentation locally) must be supported on all Unix-like systems. Additional functionality like documentation checks can rely on tools that are not available everywhere (for example, the woke snap) if there is no easily available solution otherwise. This is acceptable because the checks run on GitHub anyway, and while we want to make it possible to run them locally to save time, not being able to do so won't block updating the docs.

[ru-fu]

I'll open a PR with a suggestion for a fix (moving the manpages URL to custom_conf).

[ru-fu]

See https://github.com/canonical/sphinx-docs-starter-pack/pull/236