canonical / sphinx-docs-starter-pack

A documentation starter-pack
https://canonical-starter-pack.readthedocs-hosted.com/
10 stars 30 forks source link

Get rid of apt install in the Makefile #236

Closed ru-fu closed 1 month ago

ru-fu commented 1 month ago

For the basic functionality of the starter pack, we should not assume that we are on Ubuntu.

Therefore, undo the change of automatically determining the manpages URL (instead, add the variable to custom_conf.py so every team that needs it can decide if they want to update it manually or add some automatic processing).

Also, don't automatically install python3-env if it's missing, but return an error message that it must be installed.

dviererbe commented 1 month ago

Excepting from every team to configure the manpages_url works for me 👍🏻

Just in case, that you are interested in auto configuring the latest stable Ubuntu man page urls by default, we could still parse the latest stable Ubuntu series from the source of distro-info via Launchpad. Here is a short script that demonstrates this:

import csv
import requests
from datetime import datetime

def QueryLatestStableSeries(fallback):
    url = "https://git.launchpad.net/ubuntu/+source/distro-info-data/plain/ubuntu.csv"

    try:
        response = requests.get(url)
        response.raise_for_status()

        content = response.content.decode('utf-8').splitlines()

        now = datetime.now().date()
        latestStableSeries = None

        for row in csv.DictReader(content):
            releaseDate = datetime.strptime(row["release"], "%Y-%m-%d").date()

            if releaseDate > now:
                continue

            latestStableSeries = row["series"]

        return latestStableSeries
    except Exception as exception:
        print(f"WARNING: Falling back to Ubuntu series {fallback} for "
              "man page url version. Failed to query latest stable series. "
              "See the details:")
        print(exception)

        return fallback

if 'custom_manpages_url' in locals():
    manpages_url = custom_manpages_url
else:
    manpages_distribution = QueryLatestStableSeries(fallback="noble")
    manpages_url = ("https://manpages.ubuntu.com/manpages/"
                    f"{manpages_distribution}/en/"
                    "man{section}/{page}.{section}.html")

Note: This requires to install the python package requests

ru-fu commented 1 month ago

Just in case, that you are interested in auto configuring the latest stable Ubuntu man page urls by default, we could still parse the latest stable Ubuntu series from the source of distro-info via Launchpad. Here is a short script that demonstrates this:

Thanks! Let's leave this for teams to implement in their custom_conf.py for now. If there's common need for it, please open an issue and we can see whether we should make it commonly available.