Project Structure

[Rob Gaddi]

I'm working on a project ( https://github.com/NJDFan/register-maps 
http://register-maps.readthedocs.io/en/latest/ ) and running into some 
issues with overall project structure and documentation.

The project is a code generator that reads in a set of proprietary 
format XML files and uses them to generate output in any number of 
languages (C, Python, VHDL) as well as HTML documentation.  Input is an 
entire directory, output is an entire directory.

   registermap ./data/src --format=html --output=../docs/html

One of the things I'd like to do is to write a boilerplate README.rst 
into the target directory.  I also have Sphinx documentation; I'd like 
to incorporate all those READMEs into the HTML docs.  I'd also like to 
have something like a

   registermap --format-help vhdl

Which displays the appropriate README, ideally neatly formatted for the 
terminal and running through a pager.  You know, civilized.

So, right now I have a project setup which is

./
   doc/
     ...
   registermaps/
     __init__.py
     ...
     resource/
       vhdl/
         README.rst
         ...
       html/
         README.rst
         style.css
         ...
   README.rst
   setup.py
   ...

Output classes have a .outputname, which is both the command-line output 
name ('html') and the directory under resource that all the stuff is in.
I have a utility function in the module that allows those classes to 
register themselves against that name for the command-line tool.

Resources are accessed through pkg_resource.resource_string internal to 
the program, and the READMEs get pulled into the Sphinx docs by having a 
doc/source/outputs.rst full of include directives like

   .. include:: ../../registermaps/resource/html/README.rst

I still don't have any kind of standard way of pretty-printing and 
paging the reST to the terminal.  And, more the point, this all feels 
VERY tangled.  Like there's something that other people just know to do 
and I missed the memo.  Anyone have any ideas on a cleaner implementation?

-- 
Rob Gaddi, Highland Technology -- www.highlandtechnology.com
Email address domain is currently out of order.  See above to fix.