March 2024 - This site, and Kamaelia are being updated. There is significant work needed, and PRs are welcome.

Project Task Page: Reference Documentation automated Generation

Status: Completed
Current Developers: MH, MPS
Current "inflight" dev location: /Code/Python/Kamaelia/Tools/DocGen
Start Date: 09 March 2006
Major Milestone date: April 2007 - Auto generation of Axon & Kamaelia docs (met)
End Date: 5 Aug 2007
Date this page last updated: 5 Aug 2007
Estimated effort so far: 30


Description


Up-to-date automatically generated reference documentation is useful to users/developers. If it is automatically rebuilt and uploaded to the kamaelia website regularly then it is one less maintenance task.

Inputs

Task Sponsor: MS

Task Owner: MH

Developers: MS, MH

Users: MS, MH

Interested third parties: --

Requirements

The people listed here should be real people. Unless you have agreement however, this this should be their initials rather than name.

Relevant Influencing factors:

Outputs

Expected

Actual

Code:

Documentation generation tool:

Test Suite output generation tool:

More detailed repository/codebase introspection

Automation scripts on bbc.kamaelia.org for nightly rebuilds of docs

Nightly rebuilds of Axon and Kamaelia reference documentation now automated.

Improvements to "Compose" tool:



Realistic possibilities arising as a result of activity on this task

--

Tasks that directly enable this task (dependencies)

Sub Tasks

Task Log

Discussion


Documentation generation is capable of building reference documentation both: for Kamaelia components and prefabs; and also for Axon classes and functions

Part of this work included a ground-up rewrite of Kamaelia.Support.Data.Repository to:


Running systems:

-- Matt, 11 April 2007

Branch private_MH_20070618_docgen_improvements (ready for merge)

The repository introspection code has been rewritten so it now parses source files using a process more akin to execution - it tracks imports, class and function declarations, and assignment statements as it parses the code. This means that, for example, it will no longer be fooled by something like this:

from Axon.Component import component as C

class MyComponent(C):
    ....

MyActualComponent = MyComponent
MyComponent = None

This new code will correctly determine that MyActualComponent inherits from Axon.Component.component and that MyComponent doesn't actually reference a component once the module is imported.

This has therefore made it possible to determine what methods are inherited from base classes. The documentation generator can therefore provide more comprehensive class documentation for Axon. Mappings of symbols to URLs can also be exported from a documentation build to a file; and then re-imported for another build - thereby making it possible to cross-link from Kamaelia component docs back to Axon docs.

The nightly documentation build automation scripts (held in /Sketches/MH/AutoDocGeneration) have been updated to use these new capabilities, but this has not yet been uploaded to bbc.kamaelia.org

Finally, the "Compose" tool has also been modified so it no longer imports components - but instead uses the introspection data that comes from this repository scanning code.

-- Matt, 19 June 2007