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.
--
https://mail.python.org/mailman/listinfo/python-list
