[EPIC] Pos repository migration to Pulp organization

[pedro-psb]

To make this package more maintanable (by other people other than me), I'll keep track of some refactors and improvements that would be nice to have before moving this to Pulp organization.

Refactors

Navigation

• Don't use string based content-definition (e.g. "{repo}/docs/user/{content}") link
  • Reason: This requires unnecessary string-parsing/conversion steps that clutter the code without any obvious benefit.
  • Alternative: Switch to dataclass-based declaration
• Better constants/options/enums organization (related to the previous one)
  • Reason: There is a set of identifier options for persona, content-categories and repo-types, and they have related display names in the docs. This relation should be globally defined
  • Alternative: Use enums or similar scoped classes consistently

Repositories

• Decouple Report from Repo (move this out)
  • Reason: this info is not used by Repo instances (unnecessarily bloats the class) and makes it confusing to handle reports.
  • Alternative: move it to another object dedicated to reports
• Re-model Repos, Repo, SubPackages to better separate concerns
  • Reason: With subpackages, the concern of handling repositories (info required for download, path, etc) were mixed with package concerns (display name, relative location in a repository)
  • Alternative: implement Repo and Package (a generalization of subpackages and single-package repo) with this separation of concerns.
• Create PackagesHandler to be responsible for handling the process of download -> placement -> installation
  • I need to better define those steps conceptually so its easier to understand what is happening and each stage.
• Remove hardcoded test fixture from codebase here.
  • Reason: that's a code smell that the code is not very testable
  • Alternative: consolidate repolist.yml overriding and use that in the tests.

Testing

• Unit:
  • AggregationUtils: related to generating nav structures parametrically
  • Repository: related to download and source file placement
  • Package: related to docs file placement, because more than one docs can live in the same source
  • General Utils: not much here
• Functional (no download from network or external API hits):
  • Building
  • Serving (how?)
  • Caching
  • Automatic local-checkout discovery
  • Navigation rendering (selenium or similar)
• Integration (hits the network)
  • Sanity production check

Docs

• Generated Reference (mkdocstrings)
• Onboarding page: Architecture, concepts general data-flow