Refactor #100


Reorganize documentation

Added by rbarlow over 9 years ago. Updated almost 5 years ago.

Start date:
Due date:
% Done:


Estimated time:
Platform Release:
Sprint Candidate:
Documentation, Pulp 2


We had a discussion about this on an etherpad. These are the results of that discussion:

Notation: Each separate page is given a number or letter based on its position in the user facing heirarchy. Subsections that are viewed on the same page are given bullets if they may be worth moving or consolidating. I ignored other subsections for "brevity"
Each item in the proposed new structure should indicate the existing page in the current structure or new if it does not exist.
Built in to RTD, the tree on the left side is limited to 2 depth, so pages that are "i" level and deeper are not directly accessable from the left side. This isn't necessarily a problem, but the page will have to be set up with this in mind. A list of sections that this affects directly is below the structure.
Current Structure
1. User Guide
A. Introduction

What pulp can do


Goal of this guide

B. Release Notes
i. Master
ii. 2.6
iii. ...

C. Installation

D. Tuning and Scaling
E. Pulp Broker Settings
F. Server

Conflicting Operations

Recovery from Worker Failure




G. Authentication


Apache Preauthentication



H. Admin Client
i. Introduction
ii. Authentication
iii. Consumer
iv. Events
v. Nodes
vi. Repositories
vii. Orphaned Content Units
viii. Inspecting the Server
ix. Tasks

I. Consumer Client
i. Introducing the Pulp Consumer Client
ii. Registering
iii. Update
iv. Binding
v. History
vi. Status
vii. Nodes
viii. Repository Search
J. Nodes




Enabling Repositories

Repository Publishing

Registration & Activation

Binding To Repositories

Child Synchronization

Quick Start

Tips & Troubleshooting

K. Content Sources

Defining A Content Source


L. General Reference

Resource IDs

Date and Time Units


Client Argument Boolean Values


L. Glossary
M. Troubleshooting

2. Developer Guide
A. How to Contribute

For New Contributors

Contribution Checklist

i. Developer Setup
ii. Branching Model
iii. Merging
iv. Creating Documentation
v. Bugs (Links back to root bugs)
vi. Building Instructions

B. Architecture



Git Repositories

C. Conventions
i. Searching

Search Criteria

Unit Association Criteria

Search API

ii. Exception Handling
iii. Error Details
iv. Error Codes
v. Synchronous and Asynchronous Call


Call Report

vi. Scheduled Tasks

D. Policies
i. Compatibility
ii. Style


In-code Documentation




iii. Testing


Python Libraries

Testing Utilities



iv. Versioning (move to build?)

Python Package Version

RPM Package Version

Lifecycle Example

v. Release Management (Remove, check for necessary info to put into build section)
vi. Building RPMs (Remove, now in build)

E. Implementing support for New Types
i. Server Plugins
1) Documentation
a) Type Definitions
b) Migrations
c) Importers
d) Distributors
e) Plugin Conventions
f) Plugin Example

ii. Client Extensions
1) extensions
2) extension example

iii. Agent Handlers
1) Handlers
a) handlers
b) handler example

F. Integrating with Pulp
1) Authentication
2) Consumer APIs
a) Register, Update, and Unregister
b) Repository Binding
c) Retrieval
d) Content Management
e) Scheduled Content Management
f) Consumer History
g) Unit Profiles
h) Content Applicability

3) Consumer Group APIs
a) Create, Delete, and Update
b) Group Membership
c) Repository Binding
d) Content Management
4) Repository APIs
a) Creation, Deletion, and Configuration
b) Retrieval
c) Synchronization
d) Publication
e) Content Retrieval
5) Repository Group APIs
a) Creation, Delete, and Update
b) Retrieval
c) Repository Membership
d) Repository Group Distributors
e) Publication

6) Content Manipulation APIs
a) Uploading Content
b) Copying Units Between Repositories
c) Unassociating Content Units from a Repository
d) Orphaned Content
e) Retrieval
f) Content Sources
g) Catalog

7) Dispatch APIs
a) Task Management

8) Event Listener APIs
a) Event Listener Creation and Configuration

9) User APIs
a) Create, Update, and Delete
b) Retrieval

10) Role APIs
a) Create, Update, and Deletesd
b) Retrieval

11) Permission APIs
a) Grant/Revoke permissions from User or Role
b) Retrieval

12) Status

ii. Events
1) Email Notifier
2) HTTP Notifier
3) AMQP Notifier
4) Repository Synchronize and Publish Events

iii. Pulp Nodes

G. Glossary

H. Troubleshooting
3. Bugs
List of sections not accessible by left side

Individual Release notes (1B) This one makes sense that the root should just be an index to each set of release notes.

Admin Client (1H)

Consumer Client (1I)

Implementing support for new types. This one is really really nested

Integrating with pulp

New Structure
1. Index (1A)

What is Pulp

How to use this document

Link to each Plugin Docs page

2. Setup (1C) <--this probably needs to cover both install and upgrade?
A. installation (link to dev installation)
B. upgrading
C. release notes (1B)

3. Architecture

Server Components(1F)

Conflicting Operations (1F)

4. Conventions (1C --recursive)
A. Searching
B. Exception Handling
C. Error Details
D. Syn and Async
E. Schedules tasks
F. Incorporate from General Reference(1L)

5. Configuration
A. Pulp Broker Settings (1E)
B. Making a backup(1F)
C. Authentication (1G)
D. Content Source (1K)
E Tuning and Scaling
6. Admin Client (1H)
7. Consumer Client (1I) <- thats "one eye"
8. Pulp Nodes (2 F iii) < Not sure where this belongs*
9. Integration Guide
A. REST API Reference (From 2F i)
B. Events
10. Contributor Guide
index - checklist, note (2A)
A. Contributor setup (2A i)

Add section about installing plugins

B. Branching and Merging (2A ii, 2A iii)
C. Documentation (2A iv)
D. Policies (2D except for building RPM's)





Release management

E. Building Instructions(2A vi, 2D vi)
11. Troubleshooting
A. Recovery from a failed worker (1F)
12. Bugs < I don't think this needs a toplevel
< I would prefer that users have really easy access to info regarding reporting a
< bug. If you don't want this top level, where do you think it should go?
13. Glossary
???? Implementing Support for New types < This is a huge document that is very very nested. As it is, it is pretty difficult to access, it seems unlikely that a community member would be able to implement support for a new type at this time [citation needed]. I have no idea what to do with this section. Thoughts?

Actions #1

Updated by rbarlow about 9 years ago

  • Tracker changed from Task to Refactor
Actions #2

Updated by bmbouter about 9 years ago

  • Tags Sprint Candidate added
Actions #3

Updated by mhrivnak about 9 years ago

  • Priority changed from High to Normal
  • Tags deleted (Sprint Candidate)
Actions #4

Updated by bmbouter about 9 years ago

  • Category deleted (1)
  • Tags Documentation added

Documentation is now a Tag not a Category.

Actions #5

Updated by bmbouter about 5 years ago

  • Status changed from NEW to CLOSED - WONTFIX
Actions #6

Updated by bmbouter about 5 years ago

Pulp 2 is approaching maintenance mode, and this Pulp 2 ticket is not being actively worked on. As such, it is being closed as WONTFIX. Pulp 2 is still accepting contributions though, so if you want to contribute a fix for this ticket, please reopen or comment on it. If you don't have permissions to reopen this ticket, or you want to discuss an issue, please reach out via the developer mailing list.

Actions #7

Updated by bmbouter almost 5 years ago

  • Tags Pulp 2 added

Also available in: Atom PDF