Restructure a API documentation

Topics: Conceptual Topics, Features, General Discussion
Jul 24, 2008 at 9:02 AM
Hi Dave

It's me again. I have second thing I would like to ask. Currently I'm trying to build documentation for a web service but for clients. I've used genearated proxy class as a source for documentation so I will have exactly the same classes as a service client. Problem is that it ends with one service class (let's name it MyService), quite few dozen of request and response message classes and almost hundred of classes that are used in messages. So finally my TOC is flat list of classes sych as:
- AuthenticateRequest
- Authenticate Response
- BatchIdentifier
- BatchRequest
- BatchResponse
- Customer
- Department
- Service
- User

etc.

It look terrible and it's very difficult to find anythng there. What I would like to do, is to create some conceptual topics and group generated topics underneath into something like that:

- Messages
    - Request Messages
        - AuthenticateRequest
        - BatchRequest
    - Response Messages
        - Authenticate Response
        - BatchResponse
- Base classes
    - BatchIdentifier
    - Customer
    - Department
    - User
- Service

Is somethign like that possible, or if it's not, could that be something you can consider as an usefil feature?
Coordinator
Jul 24, 2008 at 5:39 PM
Hi,

I had planned to add support for TOC grouping algorithms in the last release but it didn't make it in.  I'll probably add it to 1.12.0.

Group Reference Topics in TOC
http://www.codeplex.com/DocProject/WorkItem/View.aspx?WorkItemId=15220

Although what you're asking for is the ability to inject conceptual topics into the auto-generated reference TOC and also have full control over its arrangement.  Sounds like a useful feature, so I'll append it to the grouping work item and add support in the next release.

Currently there's no supported way to automate Topic Explorer so you'll have to wait until I add support for this feature in order to use it in the UI.  However, you could try injecting a dynamic build step that arranges the nodes in the toc.xml file (in the working directory) in whichever order you'd like them to appear.  Since the final toc.xml file contains conceptual topics too you could, theoretically, freely mix them into the auto-generated reference TOC, which has already been merged into the toc.xml file too.

- Dave
Jul 25, 2008 at 12:52 PM
That's great, I will wait till next release then.