Pulp documentation working group forming

Announcements
#1

A working group is being formed to completely remake Pulp docs. The goal of this group will be to produce a unified documentation site. Please post here if you would like to join this working group.

1 Like
#2

Wanna join it. Should we have a “Documentation” category here on the forum?

1 Like
#3

Count me in, please!

1 Like
#4

I’d like to join!

1 Like
#5

Count me in too :slight_smile:

2 Likes
#6

I’m in

2 Likes
#7

I won’t be able to attend to the meeting, so I’ll leave my initial “pratical” notes on this.

Some questions

  • What doc-lib should we use?
    • mkdocs - good plugin ecosystem and uses markdown
    • docusaurus (md/js) - really like UI, uses markdown but JS
    • sphinx - rst
    • …
  • Where each plugin documentation should live?
    • monorepo docs - more hard for each team to maintain, easier to build
    • multi-repo docs - more easy for each team to maintain, more hard to build
  • How to handle multiple versions for each plugin? (single site docs)
    • use “introduced in v1.2.3” and legacy section for relevant stuff
    • two builds:
      • aggregation build on the main doc-site (build/versioned on pulp-core releases, because it’s frequent)
      • stand-alone for archiving purposes (like published with github pages for each plugin, most reliable if someone is looking for a specific old-release thing).
  • How can the migration happen?
    • gradual-migration:
      • each plugin migrates to a stand-alone version (complying with the unified doc stack)
      • pulpcore (assuming it hosts the main “doc”) migrates last with the aggregation step.
    • instant-migration
      • each plugin creates an alternative offline doc version but keeps the old one running
      • synced up deprecation of old docs and activation of new
  • How to handle redirect from old pages?
    • …

Resources

Proposed Principles

My personal take on those ideas:

on structure

  • doc-source and plugin-code should live in the same place
  • there is a single main pulp website that hosts all plugin’s docs as an unified experience
  • there are secondary standalone versioned docs (“archive-doc”) for each plugin

on build/release

  • the main doc publication build is defined by pulpcore releases.
  • the plugin’s archive-docs publication is defined by each plugin release independently.

on migration

  • each plugin migrates first, then pulpcore migrates, releasing the new docs
  • old links get redirected to new site, preferably on relevant sections
#8

Thanks for the great notes Pedro. I added them to our agenda for the next time we meet on December 1, 2023[0].

Our meeting today was lightly attended so we only discussed one topic. We agreed that I will take action to setup newdocs.pulpproject.org that will be published from the pulpcore repository.

[0] Docs Working Group - HackMD

2 Likes
#9

I take it the “newdocs” should only be ephemeral and go away as soon as possible (We cannot possibly maintain two docs efforts simultaneously).
Can we give it a more descriptive ephemeral name like “staging-docs.pp.o”?

1 Like
#10

I’ve requested that the hostname be staging-docs.pulpproject.org. I am still waiting on the DNS record to be created though.

3 Likes
#11

And it’s working!

1 Like