87 lines
2.0 KiB
Python
Executable File
87 lines
2.0 KiB
Python
Executable File
#!/usr/bin/env python
|
|
"""Generate *.rst files to mirror *.py files in a Python library.
|
|
|
|
This script is conceptually similar to the sphinx-apidoc script bundled with
|
|
Sphinx:
|
|
|
|
http://sphinx-doc.org/man/sphinx-apidoc.html
|
|
|
|
We produce different *.rst output, however.
|
|
|
|
"""
|
|
from __future__ import print_function, unicode_literals
|
|
import os
|
|
|
|
|
|
w = lambda f, s, *a, **kw: print(s.format(*a, **kw), file=f)
|
|
|
|
|
|
def rst_for_module(toc_path):
|
|
"""Given a toc_path, write rst and return a file object.
|
|
"""
|
|
|
|
f = open(toc_path + '.rst', 'w+')
|
|
|
|
heading = ":mod:`{}`".format(os.path.basename(toc_path))
|
|
dotted = toc_path.replace('/', '.')
|
|
|
|
w(f, heading)
|
|
w(f, "=" * len(heading))
|
|
w(f, ".. automodule:: {}", dotted)
|
|
|
|
return f
|
|
|
|
|
|
def rst_for_package(root, dirs, files):
|
|
"""Given ../mylib/path/to/package and lists of dir/file names, write rst.
|
|
"""
|
|
|
|
doc_path = root[3:]
|
|
if not os.path.isdir(doc_path):
|
|
os.mkdir(doc_path)
|
|
|
|
|
|
# Start a rst doc for this package.
|
|
# =================================
|
|
|
|
f = rst_for_module(doc_path)
|
|
|
|
|
|
# Add a table of contents.
|
|
# ========================
|
|
|
|
w(f, ".. toctree::")
|
|
|
|
def toc(doc_path, name):
|
|
parent = os.path.dirname(doc_path)
|
|
toc_path = os.path.join(doc_path[len(parent):].lstrip('/'), name)
|
|
if toc_path.endswith('.py'):
|
|
toc_path = toc_path[:-len('.py')]
|
|
w(f, " {}", toc_path)
|
|
return os.path.join(parent, toc_path)
|
|
|
|
for name in sorted(dirs + files):
|
|
if name in dirs:
|
|
toc(doc_path, name)
|
|
else:
|
|
if not name.endswith('.py'): continue
|
|
if name == '__init__.py': continue
|
|
|
|
toc_path = toc(doc_path, name)
|
|
|
|
|
|
# Write a rst file for each module.
|
|
# =================================
|
|
|
|
rst_for_module(toc_path)
|
|
|
|
|
|
def main():
|
|
library_root = os.environ['AUTOLIB_LIBRARY_ROOT']
|
|
for root, dirs, files in os.walk(library_root):
|
|
rst_for_package(root, dirs, files)
|
|
|
|
|
|
if __name__ == '__main__':
|
|
main()
|