Skip to content

Make unready containerized docs not ready #4899

Merged
jafiala merged 9 commits into
theforeman:masterfrom
jafiala:update-incomplete-containerized-guides-SAT-45577
Jun 5, 2026
Merged

Make unready containerized docs not ready #4899
jafiala merged 9 commits into
theforeman:masterfrom
jafiala:update-incomplete-containerized-guides-SAT-45577

Conversation

@jafiala

@jafiala jafiala commented Jun 3, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

What changes are you introducing?

Hide contents of unready containerized guides, and include the "guide not ready" module.

Why are you introducing these changes? (Explanation, links to references, issues, etc.)

https://redhat.atlassian.net/browse/SAT-45577

Anything else to add? (Considerations, potential downsides, alternative solutions you have explored, etc.)

Discussed on matrix

Contributor checklists

  • I am okay with my commits getting squashed when you merge this PR.
  • I am familiar with the contributing guidelines.

Please cherry-pick my commits into:

  • Foreman 3.19/Katello 4.21
  • Foreman 3.18/Katello 4.20 (Satellite 6.19)
  • Foreman 3.17/Katello 4.19
  • Foreman 3.16/Katello 4.18 (Satellite 6.18; orcharhino 7.6, 7.7, and 7.8)
  • Foreman 3.15/Katello 4.17
  • Foreman 3.14/Katello 4.16 (Satellite 6.17; orcharhino 7.4; orcharhino 7.5)
  • Foreman 3.13/Katello 4.15 (EL9 only)
  • Foreman 3.12/Katello 4.14 (Satellite 6.16; orcharhino 7.2 on EL9 only; orcharhino 7.3)
  • We do not accept PRs for Foreman older than 3.12.

@github-actions github-actions Bot added Needs tech review Requires a review from the technical perspective Needs style review Requires a review from docs style/grammar perspective labels Jun 3, 2026
@github-actions

github-actions Bot commented Jun 3, 2026 •
edited
Loading

Copy link
Copy Markdown

The PR preview for c8a0cf1 is available at theforeman-foreman-documentation-preview-pr-4899.surge.sh

The following output files are affected by this PR:

show diff

show diff as HTML

@jafiala jafiala marked this pull request as ready for review June 3, 2026 11:16
@jafiala jafiala removed the Needs tech review Requires a review from the technical perspective label Jun 3, 2026
@jafiala

jafiala commented Jun 3, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor Author

This is another tricky one to review.

Each guide (except exceptions below) is hidden from containerized builds, and the contents are replaced with the Not Ready module.

Exceptions:

  1. Connected installation (already prepared for containerization)
  2. Release notes (not sure, I don't think it makes sense to have a containerized build here, but also "not ready" does not fit)
  3. doc-Installing_Proxy already has that include, so containerized was just added to the existing conditional.
  4. A few guides already have some meaningful conditionals for containerized, which I preserved. That way, we don't lose track of the sections that are ready.
    • doc-Configuring_User_Authentication (4 occurrences at lines 7, 10, 22, 55)
    • doc-Installing_Server_Disconnected (3 occurrences at lines 10, 13, 32)
    • doc-Upgrading_Project (3 occurrences at lines 9, 12, 18)

The diff is huge, so I split the HTML diff into the individual guides.

Then, a naive Claude summarized the changes, which correspond to the expected changes.

A reviewer should review the actual changes, which are clear and manageable, and then can replicate my agentic approach, which should be sufficient to show that only the intended changes are made.

+++Agentic review report follows+++

Summary of Changes Across 75 Diff Files
Overview
This directory contains 75 HTML diff files showing changes between old documentation and the preview/nightly build. The diffs represent a complete content replacement across all guides and flavors.

Scope
25 unique guides (documentation topics)
3 flavors per guide:
containerized-katello
containerized-orcharhino
containerized-satellite
Total combinations: 25 guides × 3 flavors = 75 diff files

Guides Affected
Administering_Project
Configuring_Load_Balancer
Configuring_User_Authentication
Configuring_virt_who_VM_Subscriptions
Hammer_CLI
Hammer_Reference
Installing_Proxy
Installing_Server_Disconnected
Integrating_Provisioning_Infrastructure_Services
Managing_Configurations_Ansible
Managing_Configurations_Puppet
Managing_Configurations_Salt
Managing_Content
Managing_Hosts
Managing_Organizations_and_Locations
Managing_Security_Compliance
Monitoring_Project
Planning_for_Project
Project_Ansible_Collection
Project_API
Provisioning_Hosts
Tuning_Performance
Updating_Project
Upgrading_Project
Upgrading_Project_Disconnected

Nature of Changes
Every single guide has been replaced with a placeholder page containing:

Removed:
All original guide content (ranging from minimal content to 10,000+ lines)
Complete table of contents structures
All sections, procedures, concepts, and reference material

Added:
Simple placeholder page with heading: "1. Guide not ready yet"
Abstract text: "This guide is not ready yet."
Community contribution message pointing to GitHub repository
Updated body class: class="book toc2 toc-left" (adds ToC styling)

Impact
This represents a complete documentation reset where all 25 guides across all 3 deployment flavors have been temporarily replaced with "not ready yet" placeholders, likely indicating a major documentation restructuring or rebuild in progress for the nightly/preview build.

@jafiala jafiala requested a review from aneta-petrova June 3, 2026 13:26
aneta-petrova
aneta-petrova reviewed Jun 3, 2026
View reviewed changes
Comment thread guides/doc-Administering_Project/master.adoc
aneta-petrova
aneta-petrova reviewed Jun 3, 2026
View reviewed changes
Comment thread guides/doc-Administering_Project/master.adoc
aneta-petrova
aneta-petrova reviewed Jun 4, 2026
View reviewed changes
Comment thread guides/doc-Installing_Proxy/master.adoc Outdated
aneta-petrova
aneta-petrova reviewed Jun 4, 2026
View reviewed changes
Comment thread guides/doc-Installing_Proxy/master.adoc Outdated
Comment thread guides/doc-Installing_Proxy/master.adoc
aneta-petrova
aneta-petrova reviewed Jun 4, 2026
View reviewed changes
Comment thread guides/doc-Configuring_User_Authentication/master.adoc Outdated
maximiliankolb
maximiliankolb approved these changes Jun 5, 2026
View reviewed changes

@maximiliankolb maximiliankolb left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM. I also built the docs locally for all flavors because I am somewhat surprised that we do not have to hide some links for containerized builds.

@jafiala jafiala added style review done No issues from docs style/grammar perspective and removed Needs style review Requires a review from docs style/grammar perspective labels Jun 5, 2026
@jafiala jafiala merged commit 90033e9 into theforeman:master Jun 5, 2026
8 of 9 checks passed
jafiala added a commit that referenced this pull request Jun 5, 2026
@jafiala
Make unready containerized docs not ready (#4899)
25e5b90 
* Make InstallingSmartProxy unready

* Add unready includes to remaining containerized guides

* Add katello conditionals

* Add linebreaks for visibility

* Remove extra endif

* Add katello conditional

* Fix ifdef

* Revert ConfiguringUserAuthentication

* Fix nested conditional logic

(cherry picked from commit 90033e9)
@jafiala

jafiala commented Jun 5, 2026

Copy link
Copy Markdown
Contributor Author

Cherry-picked to 3.19 in 25e5b90

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@aneta-petrova aneta-petrova aneta-petrova left review comments
@Lennonka Lennonka Lennonka left review comments
@maximiliankolb maximiliankolb maximiliankolb approved these changes

Assignees

No one assigned

Labels

style review done No issues from docs style/grammar perspective

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

4 participants

@jafiala @maximiliankolb @aneta-petrova @Lennonka