From fb75d0f848f4303444282655c57792cf93d66807 Mon Sep 17 00:00:00 2001 From: ridiculousfish Date: Sun, 10 Feb 2019 14:38:04 -0800 Subject: [PATCH] Parse out command descriptions from files for Sphinx man pages sphinx expects that the description for a command (as appearing in its man page) be provided in conf.py, not in the rst file itself. LLVM handles this with some custom Python code that parses it out of the file. Do the same thing in fish. --- sphinx_doc_src/conf.py | 12 +++++++++++- 1 file changed, 11 insertions(+), 1 deletion(-) diff --git a/sphinx_doc_src/conf.py b/sphinx_doc_src/conf.py index 2ffcc5f3c..ffd8a2ee8 100644 --- a/sphinx_doc_src/conf.py +++ b/sphinx_doc_src/conf.py @@ -144,6 +144,16 @@ latex_documents = [ # -- Options for manual page output ------------------------------------------ +def get_command_description(path): + """ Return the description for a command, by parsing its first line """ + with open(path) as fd: + title = fd.readline() + if ' - ' not in title: + raise SphinxWarning('No description in file %s' % os.path.basename(path)) + _, desc = title.split(' - ', 1) + return desc.strip() + + # One entry per manual page. List of tuples # (source start file, name, description, authors, manual section). man_pages = [ @@ -153,7 +163,7 @@ man_pages = [ for path in sorted(glob.glob('cmds/*')): docname = strip_ext(path) cmd = os.path.basename(docname) - man_pages.append((docname, cmd, '', '', 1)) + man_pages.append((docname, cmd, get_command_description(path), '', 1)) # -- Options for Texinfo output ----------------------------------------------