docs: Merge all documentation into a single one

These changes allow to build all SWH documentations (developmment, system administration and user) using a single sphinx-build command, meaning they are now merged into a single one with shared index of references.

Development documentation is now rooted to docs/devel, user one to docs/user and sysadmin one to docs/sysadm so a good amount of files were moved.

A couple of configuration files and makefiles were updated to reflect that change and the building / cleaning processes were made more reliable.

Calling make in root directory of swh-docs will execute the development build of the documentation in a tox environment while calling make in docs folder will use the current virtualenv.

It remains possible to build each documentation in a standalone way by calling make in their root directory.

Related to #4496 (closed)

changed milestone to %Bootstrap user documentation on docs.s.o

assigned to @anlambert

marked this merge request as draft

changed title from docs: Merge all documentation into a single one (WIP) to Draft: docs: Merge all documentation into a single one

added 1 commit

• 8956f0c7 - docs: Merge all documentation into a single one (WIP)

Compare with previous version

added 2 commits

• b3ef6310 - 1 commit from branch swh/devel:master
• 5dc22111 - docs: Merge all documentation into a single one (WIP)

Compare with previous version

marked this merge request as ready

added 1 commit

• 74ea1152 - docs: Merge all documentations into a single one

Compare with previous version

added 1 commit

• be771362 - docs: Merge all documentations into a single one

Compare with previous version

added 2 commits

• e2308580 - 1 commit from branch swh/devel:master
• 38a5c9fe - docs: Merge all documentations into a single one

Compare with previous version

ahaha -2023 now (same on all pages change here ¯_(ツ)_/¯ but fine either way ;)

changed this line in version 8 of the diff

lgtm

one remark for copyright range date inline.

And one question regarding redirects:

• are any installed?
• or do we accept to break all links during that transition (for once with a disclaimer somewhere)?

approved this merge request

mentioned in merge request swh/infra/ci-cd/swh-jenkins-jobs!154 (merged)

added 2 commits

• 75869847 - 1 commit from branch swh/devel:master
• eafc08b4 - docs: Merge all documentations into a single one

Compare with previous version

changed the description

Thanks a lot for this work!

There's a few intersphinx links left to the swh-sysadm separate docs build, may be worth cleaning them up directly (grep for swh-sysadm:).

I don't think the transition will break any links, as long as we publish this new documentation at the root of https://docs.softwareheritage.org/ (which was our intention? See discussion in swh/infra/ci-cd/swh-jenkins-jobs!154 (merged))

There's a few intersphinx links left to the swh-sysadm separate docs build, may be worth cleaning them up directly (grep for swh-sysadm:).

Thanks for spotting, there is also a couple of swh-devel ones to remove.

I don't think the transition will break any links, as long as we publish this new documentation at the root of https://docs.softwareheritage.org/ (which was our intention? See discussion in swh/infra/ci-cd/swh-jenkins-jobs!154 (merged))

That would be ideal indeed to not break the current links or we could redirect to docs.swh.org/sphinx/devel/* ?

That would be ideal indeed to not break the current links or we could redirect to docs.swh.org/sphinx/devel/* ?

I'm not fond of the idea of adding an implementation detail (/sphinx/) to the canonical path of all our documentation, and I don't foresee any blockers to pointing docs.softwareheritage.org directly to the new root of the built documentation.

Is removing the target option in jenkins job conf swh/infra/ci-cd/swh-jenkins-jobs!154 (diffs) is sufficient to upload at the root ?

I think it's fine to keep the target option (that lets us keep the old doc around if we need to revert), and we can move the apache2 document root to the subdirectory.

Ack, that's a safe move indeed.

Ah, and the question I asked on IRC:

The TOC on the left column of the devel main page https://jenkins.softwareheritage.org/job/DDOC/job/builds/25/SWH_20Documentation/devel/index.html is pretty empty; would it be possible to give it one more level of toctree?

sure, looks better indeed

added 3 commits

• 04b92104 - docs/index: Bump toctree level
• ce573eaa - docs: Remove no longer needed intersphinx references
• 5be5fbd9 - Bump years in license headers

Compare with previous version

added 5 commits

• b6a7097a - 1 commit from branch swh/devel:master
• 736f4d44 - docs: Merge all documentations into a single one
• a31c7425 - docs/index: Bump toctree level
• b28f4381 - docs: Remove no longer needed intersphinx references
• ac47a5bd - Bump years in license headers

Compare with previous version

added 4 commits

• 0e55968d - docs: Merge all documentations into a single one
• bf010f1a - docs/index: Bump toctree level
• da0c9469 - docs: Remove no longer needed intersphinx references
• 64e03f5e - Bump years in license headers

Compare with previous version

enabled an automatic merge when the pipeline for 64e03f5e succeeds

merged

mentioned in commit swh/infra/puppet/puppet-swh-site@4be7726b