Created
January 20, 2017 19:58
-
-
Save daknuett/eae20730aa58bc7c60c740188b601b39 to your computer and use it in GitHub Desktop.
Extract rst documentation from (non-python) sourcefiles
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| #!/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) |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment