Update sphinx version

[vitaut]

Update sphinx (and breathe) version used in documentation build.

[kloczek]

Please do update sphinx but try to detct is sphinx installed and use it.

[vitaut]

As explained elsewhere, the documentation build process will use a pinned version of sphinx and you don't need to extract the docs yourself in the first place.

[alexezeder]

Another solution that comes to my mind is that the documentation build process probably should be executed in some prepared environment. For example, if CI builds the doc CMake target in some Docker container (or just using the same environment preparation step all the time) with preinstalled libraries (Sphinx, Breathe, less, clean-css, maybe more) of defined versions then the output is always the same.
This is needed for documentation in release assets and maybe website. Also, I think, that the final release asset shouldn't have any sources or build configurations for documentation, because html documentation is already presented in it. Also, there wouldn't be any option to build documentation from this archive, because looks like end-users not supposed to do this.
But if someone wants to build documentation on their own machine when they clone entire repo - why shouldn't they?
Do they have to install all the required packages? Yes, because dependencies are dependencies.
Some specific versions of these packages? No, wherever versions they want.
Is the broken documentation on their PC an {fmt} issue? No, documentation build is supposed to work correctly with the defined environment only.
Should a proper way to build documentation be presented in repo? Yes, in form of Docker file or some script, in other words, it should be the same as used in CI build for documentation.

[kloczek]

For example, if CI builds the doc CMake target in some Docker container (or just using the same environment preparation step all the time) with preinstalled libraries (Sphinx, Breathe, less, clean-css, maybe more) of defined versions then the output is always the same.

All those components are alavailable in every Linux distribution as packages.
If you want walk that path .. why you are not going download in build process source code and build cmake, glibc and gcc?
Do you really want to walk that path?
Usullay all piublic CIs envs proviides just raw system .. not flatpack or docker.
Please do not try to overthink how to build sometbig., Just dectect is what you need is installed and exit with non-zero if sometning is missing.

Building or not documentation should be possible to controll as cmake option. Full stop.
This is how it is done in every other project if maintainets understands properly for waht is build tooling.

[alexezeder]

If you want walk that path .. why you are not going download in build process source code and build cmake, glibc and gcc?

I was talking about documentation build process only, why are there glibc and gcc? As far as I know there are only few dependencies that should be installed for that: cmake, python, doxygen, sphinx, breathe, less, clean-css. For now versions of some of these are not specified (python, doxygen, less, clean-css), some are specified (cmake, sphinx, breathe). In my opinion if there are any incompatibilities between version they should be explicitly specified to build documentation without any problems in future. It's just should be easier for maintainers to check a documentation build once, freeze all dependencies and use these dependencies knowing that they are just working. When it is time to update some dependency you just update it, check that documentation is still correct, freeze it, that's all.

Please do not try to overthink

I think it's not overthinking it's just a better approach as well as removing documentation target from release asset because it's prebuilt in this asset.

Just dectect is what you need is installed and exit with non-zero if sometning is missing.

Yes, I didn't say a word against that.

Building or not documentation should be possible to controll as cmake option.

But if you are able to control documentation build by some CMake option then there is no problem with documentation for you, did I understand that correctly?

[kloczek]

Just executed some oneliner across my rpm packages spec files:

[tkloczko@barrel SPECS]$ grep 'BuildRequires:   cmake$' -l * | xargs grep 'BuildRequires:       python3dist(sphinx)$' -l | xargs awk '/^VCS:/ {print $2}'
https://github.com/rpm-software-management/createrepo_c/
https://github.com/rpm-software-management/dnf-plugins-core/
https://github.com/rpm-software-management/dnf/
https://github.com/pmachata/dwgrep/
https://github.com/fmtlib/fmt/
https://github.com/krb5/krb5/
https://github.com/PJK/libcbor/
https://github.com/rpm-software-management/libcomps/
https://github.com/rpm-software-management/libdnf/
https://github.com/analogdevicesinc/libiio/
https://github.com/rpm-software-management/librepo/
https://github.com/llvm/llvm-project/
https://github.com/nfs-ganesha/nfs-ganesha/

Obove contains list of ptojests which are using cmake and python sphinx to generate documentation.
Just do not rot try to reinvent the wheel .. :)

[vitaut]

Update to sphinx 3.3 mostly done but there are a lot of issues. Will probably have to patch breathe.