Migrate to new docs

[pedro-psb]

Review Checklist:

• [x] An issue is properly linked. [feature and bugfix only]
• [x] Tests are present or not feasible.
• [x] Commits are split in a logical way (not historically).

This is enabled by this fix PR in pulp-docs.

[pedro-psb]

CI fail doesn't seem related:

flake8
.ci/scripts/check_click_for_mypy.py
MYPYPATH=pulp-glue mypy
pytest_pulp_cli/__init__.py:19: error: Unused "type: ignore" comment  [unused-ignore]
pytest_pulp_cli/__init__.py:30: error: Unused "type: ignore" comment  [unused-ignore]
Found 2 errors in 1 file (checked 74 source files)
make: *** [Makefile:28: lint] Error 1
Error: Process completed with exit code 2.

[mdellweg]

Wow, this is based on a really ancient commit. Please rebase and look for any docs changes that might have been lost here.

[pedro-psb]

Adjust the Makefile target servedocs to show the staging site.

Should I add pulp-docs to doc_requirements.txt, or we should wait until it's properly published and lives under pulp organization?

[mdellweg]

Adjust the Makefile target servedocs to show the staging site.

Should I add pulp-docs to doc_requirements.txt, or we should wait until it's properly published and lives under pulp organization?

make servedocs is what is showing you locally how the docs you write look like. And my perception is, the moment we merge this, we stop adding anything to the new docs. And the dev tool should stop helping to go the wrong way. BTW, how are the "new" docs extracted from this repository?

[pedro-psb]

And my perception is, the moment we merge this, we stop adding anything to the new docs. And the dev tool should stop helping to go the wrong way.

Makes sense. I'll add the requirement as it exists now and we can update it when it's time. One of the next goals of the working group is to move pulp-docs to pulp.

BTW, how are the "new" docs extracted from this repository?

It either gets a local checkout if there is any under ../{pulp_plugin_label} or otherwise clones it from github.com/pulp/{pulp_plugin_label} (into tmpdir). Those are copied to a doc-tmpdir under /tmp where it looks like a single docs for mkdocs.

[mdellweg]

BTW, how are the "new" docs extracted from this repository?

It either gets a local checkout if there is any under ../{pulp_plugin_label} or otherwise clones it from github.com/pulp/{pulp_plugin_label} (into tmpdir). Those are copied to a doc-tmpdir under /tmp where it looks like a single docs for mkdocs.

Sorry, I meant is there an automation around this that should be added in this PR?

[pedro-psb]

Hmm, I don't think so. It just expects it to have the structure we defined.

[mdellweg]

Hmm, I don't think so. It just expects it to have the structure we defined.

Well, I did not know that. So how is a docs update then triggered?

[pedro-psb]

Well, I did not know that. So how is a docs update then triggered?

Currently, updates get triggered manually, see here. But the idea we have discussed for publishing is that it should be triggered nightly and it will use the latest available releases of each repository.

[pedro-psb]

I rebased but totally forgot to look for updates in the files. I assumed they would be magically merged hehe.

But I'm not comfortable about doing the total switch right now. Before that we have at least to update the publishing workflow to use the latest release, so we don't have unreleased info live, and to fix the ordering mechanism, so our links are more stable.

Still, it would be nice to have a notice in the old docs pointing out that we have a live staging docs website where new changes are going. I think there is a simple way to add a "top banner" for that.

For now, I would prefer updating the files (for real this time) and adding that banner to the old docs. If you really prefer, we can do the total switch. There are some instability in the staging-docs, but its not a mission critical problem. What do you say?

[mdellweg]

Pulp-cli is publishing the "unreleased" docs anyway (currently as "nightly"). So there is nothing to loose.

[pedro-psb]

One problem with removing all content of /docs and leaving just a migration note is that most of the links will be broken for a while.

To remediate that, I could try using this redirect plugin to either: a) Point to the respective pages on staging-docs (sounds better) b) Point all links to the kind migration note which we will be left over on /docs

Later on, we may handle those redirects more generally in the server.

Should I proceed with this approach?

[pedro-psb]

An important note, the -w option does't work yet. I'm working on that.

[mdellweg]

An important note, the -w option does't work yet. I'm working on that.

I figured as much. But I think it was time for a bold step forward. Side note: mark as draft is a pretty sure way to avoid premature merging.

[pedro-psb]

I was so confident I would add the -w flag in 5m and it would work. But unfortunately, it didn't :/ I'm waiting to see if mkdocs will accept a small patch that would fix the problem, or if I'll have to change the approach.