160 lines
4.5 KiB
Python
160 lines
4.5 KiB
Python
#!/usr/bin/python3
|
|
|
|
#
|
|
# Copyright(c) 2017 Daniel Knüttel
|
|
#
|
|
|
|
# This program is free software.
|
|
# Anyways if you think this program is worth it
|
|
# and we meet shout a drink for me.
|
|
|
|
|
|
# This program is free software: you can redistribute it and/or modify
|
|
# it under the terms of the GNU Affero General Public License as published by
|
|
# the Free Software Foundation, either version 3 of the License, or
|
|
# (at your option) any later version.
|
|
#
|
|
# This program is distributed in the hope that it will be useful,
|
|
# but WITHOUT ANY WARRANTY; without even the implied warranty of
|
|
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
|
|
# GNU Affero General Public License for more details.
|
|
#
|
|
# You should have received a copy of the GNU Affero General Public License
|
|
# along with this program. If not, see <http://www.gnu.org/licenses/>.
|
|
#
|
|
# Dieses Programm ist Freie Software: Sie können es unter den Bedingungen
|
|
# der GNU Affero General Public License, wie von der Free Software Foundation,
|
|
# Version 3 der Lizenz oder (nach Ihrer Wahl) jeder neueren
|
|
# veröffentlichten Version, weiterverbreiten und/oder modifizieren.
|
|
#
|
|
# Dieses Programm wird in der Hoffnung, dass es nützlich sein wird, aber
|
|
# OHNE JEDE GEWÄHRLEISTUNG, bereitgestellt; sogar ohne die implizite
|
|
# Gewährleistung der MARKTFÄHIGKEIT oder EIGNUNG FÜR EINEN BESTIMMTEN ZWECK.
|
|
# Siehe die GNU Affero General Public License für weitere Details.
|
|
#
|
|
# Sie sollten eine Kopie der GNU Affero General Public License zusammen mit diesem
|
|
# Programm erhalten haben. Wenn nicht, siehe <http://www.gnu.org/licenses/>.
|
|
|
|
|
|
"""
|
|
alldoc -- extract reStructuredText docstrings from all
|
|
sourcefiles.
|
|
|
|
This does include non-python files/languages.
|
|
|
|
Invoke alldoc using
|
|
::
|
|
|
|
python3 alldoc.py <outfile> <infile> {<infile>}
|
|
|
|
|
|
|
|
"""
|
|
|
|
import logging
|
|
# logging.basicConfig(level = logging.DEBUG)
|
|
logging.basicConfig()
|
|
|
|
|
|
start_alldoc = [ "<alldoc>", "<doc>", "startdoc", "SDOC"]
|
|
stop_alldoc = ["</alldoc>", "</doc>", "stopdoc", "EDOC"]
|
|
|
|
def indexof(str_, substr):
|
|
"""
|
|
This is handy if you want to get the next substr.
|
|
"""
|
|
try:
|
|
return str_.index(substr)
|
|
except:
|
|
return float("inf")
|
|
|
|
def extract_docs(str_, start_alldoc = start_alldoc, stop_alldoc = stop_alldoc):
|
|
"""
|
|
Extract all docstrings starting with ``start_alldoc`` and stopping with
|
|
``stop_alldoc``.
|
|
|
|
For instance:
|
|
::
|
|
|
|
/*
|
|
<DOC>
|
|
This is a docstring
|
|
</DOC>
|
|
*/
|
|
|
|
"""
|
|
lines_done = 0
|
|
while(1):
|
|
next_doc_start, start = min([(indexof(str_, start), start) for start in start_alldoc])
|
|
if(next_doc_start == float("inf")):
|
|
logging.debug("no more docstrings found in line "+ str(lines_done))
|
|
break
|
|
logging.debug("found docstart " + start)
|
|
unused, str_ = str_[:next_doc_start], str_[next_doc_start + len(start):]
|
|
lines_done += unused.count("\n")
|
|
logging.debug("docstart is in " + str(lines_done))
|
|
doc_stop, token = min([(indexof(str_, stop), stop) for stop in stop_alldoc])
|
|
if(doc_stop == float("inf")):
|
|
raise ExtractException("unterminated docstart: " + start + " in line " + str(lines_done))
|
|
doc, str_ = str_[:doc_stop], str_[doc_stop + len(token):]
|
|
logging.debug("found docstop " + token)
|
|
yield doc
|
|
lines_done += doc.count("\n")
|
|
logging.debug("docstop is in " + str(lines_done))
|
|
|
|
def docs_from_file(path, delim = "\n\n"):
|
|
"""
|
|
Read all docstrings from one file.
|
|
"""
|
|
with open(path) as f:
|
|
logging.debug("reading file " + path)
|
|
str_ = f.read()
|
|
docs = delim.join(extract_docs(str_))
|
|
f.close()
|
|
return docs
|
|
|
|
def collect_docs(files, delim = "\n\n"):
|
|
"""
|
|
Read all docstrings from multiple files
|
|
"""
|
|
for file_ in files:
|
|
yield docs_from_file(file_, delim)
|
|
|
|
def generate_rst_head(str_, underscore = "="):
|
|
"""
|
|
Generate a rst Heading.
|
|
"""
|
|
return str_ + "\n" + underscore * len(str_) + "\n"
|
|
|
|
def generate_docfile(fname, files, delim = "\n\n", add_rst_head = True):
|
|
"""
|
|
Read all docstrings and output one file.
|
|
|
|
FIXME: try to spend less memory.
|
|
"""
|
|
f = open(fname, "w")
|
|
f.write("".join(["".join(t) for t in zip([generate_rst_head(file) for file in files] , collect_docs(files))]))
|
|
f.close()
|
|
|
|
|
|
|
|
class ExtractException(Exception):
|
|
def __init__(self, *args):
|
|
Exception.__init__(self, *args)
|
|
|
|
if __name__ == "__main__":
|
|
import sys
|
|
if(len(sys.argv) < 3):
|
|
print("Usage:", sys.argv[0], "outfile infile {infile}")
|
|
print("extract docstrings from non-python files")
|
|
print("start tokens: ", start_alldoc)
|
|
print("stop tokens: ", stop_alldoc)
|
|
sys.exit(1)
|
|
outfile = sys.argv[1]
|
|
infiles = sys.argv[2:]
|
|
try:
|
|
generate_docfile(outfile, infiles)
|
|
except Exception as e:
|
|
print("Error:", e)
|
|
sys.exit(1)
|