Pulp

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

Plugins

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

Backups

Components

Configuration

G. Authentication

Default

Apache Preauthentication

LDAP

OAuth

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

Overview

Authentication

Installation

Enabling Repositories

Repository Publishing

Registration & Activation

Binding To Repositories

Child Synchronization

Quick Start

Tips & Troubleshooting

K. Content Sources

Defining A Content Source

Recipes

L. General Reference

Resource IDs

Date and Time Units

Criteria

Client Argument Boolean Values

Services

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

Platform

Plugins

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

Overview

Call Report

vi. Scheduled Tasks

D. Policies
i. Compatibility
ii. Style

PEP-8

In-code Documentation

Naming

Indentation

Encoding

iii. Testing

Conventions

Python Libraries

Testing Utilities

Compatibility

Coverage

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
i. REST API
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)

Compatibility

Style

Testing

Versioning

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?