From ac3c7c1fa3b150ea30b823e4edc984abaa85c4df Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Fran=C3=A7ois=20Grisez?= Date: Fri, 30 Mar 2018 15:16:48 +0200 Subject: [PATCH] Doc generator: global table of content in the side pannel --- coreapi/help/doc/sphinx/CMakeLists.txt | 3 +- coreapi/help/doc/sphinx/conf.py.in | 4 +- coreapi/help/doc/sphinx/enum_page.mustache | 7 ++- coreapi/help/doc/sphinx/gendoc.py | 65 ++++++++++++++------- coreapi/help/doc/sphinx/index.rst | 11 +--- coreapi/help/doc/sphinx/index_page.mustache | 19 ++---- 6 files changed, 57 insertions(+), 52 deletions(-) diff --git a/coreapi/help/doc/sphinx/CMakeLists.txt b/coreapi/help/doc/sphinx/CMakeLists.txt index c6058f6d7..052e33ea3 100644 --- a/coreapi/help/doc/sphinx/CMakeLists.txt +++ b/coreapi/help/doc/sphinx/CMakeLists.txt @@ -29,7 +29,6 @@ if (ENABLE_SPHINX_DOC) list(APPEND DOCUMENTATION_DIRS ${DOCUMENTATION_DIR}) list(APPEND GENERATED_SPHINX_SOURCES ${DOCUMENTATION_DIR}/index.rst) endforeach(LANGUAGE_) - set(PYTHON_SCRIPTS gendoc.py ${linphone_SOURCE_DIR}/tools/abstractapi.py ${linphone_SOURCE_DIR}/tools/genapixml.py @@ -37,7 +36,7 @@ if (ENABLE_SPHINX_DOC) ${linphone_SOURCE_DIR}/tools/metaname.py ) set(MUSTACHE_TEMPLATES class_page.mustache - enums_page.mustache + enum_page.mustache index_page.mustache ) configure_file(conf.py.in source/conf.py) diff --git a/coreapi/help/doc/sphinx/conf.py.in b/coreapi/help/doc/sphinx/conf.py.in index fcff75b1a..c94d86760 100644 --- a/coreapi/help/doc/sphinx/conf.py.in +++ b/coreapi/help/doc/sphinx/conf.py.in @@ -83,7 +83,6 @@ todo_include_todos = False # The theme to use for HTML and HTML Help pages. See the documentation for # a list of builtin themes. # -#html_theme = 'alabaster' html_theme = 'classic' # Theme options are theme-specific and customize the look and feel of a theme @@ -91,6 +90,7 @@ html_theme = 'classic' # documentation. # html_theme_options = { + 'sidebarwidth': '360', 'body_max_width': '100%', 'collapsiblesidebar': 'true' } @@ -108,7 +108,7 @@ html_experimental_html5_writer = True # Side bar customization html_sidebars = { - '**': ['searchbox.html'] + '**': ['searchbox.html', 'globaltoc.html'] } # -- Options for HTMLHelp output ------------------------------------------ diff --git a/coreapi/help/doc/sphinx/enum_page.mustache b/coreapi/help/doc/sphinx/enum_page.mustache index cf6ce2564..c400e96eb 100644 --- a/coreapi/help/doc/sphinx/enum_page.mustache +++ b/coreapi/help/doc/sphinx/enum_page.mustache @@ -5,8 +5,8 @@ {{/isJava}} {{/namespace}} -{{#enums}} -{{#make_section}}{{{name}}}{{/make_section}} +{{#enum}} +{{#make_chapter}}{{{name}}} enum{{/make_chapter}} .. {{#write_declarator}}enum{{/write_declarator}}:: {{{declaration}}} @@ -35,4 +35,5 @@ {{{selector}}} {{/enumerators}} -{{/enums}} + +{{/enum}} diff --git a/coreapi/help/doc/sphinx/gendoc.py b/coreapi/help/doc/sphinx/gendoc.py index 76cc77113..eecedda17 100755 --- a/coreapi/help/doc/sphinx/gendoc.py +++ b/coreapi/help/doc/sphinx/gendoc.py @@ -32,6 +32,10 @@ import metadoc class RstTools: + @staticmethod + def make_part(text): + return RstTools.make_section(text, char='#', overline=True) + @staticmethod def make_chapter(text): return RstTools.make_section(text, char='*', overline=True) @@ -170,6 +174,9 @@ class SphinxPart(object): def isNotJava(self): return not self.isJava + def make_part(self): + return lambda text: RstTools.make_part(pystache.render(text, self)) + def make_chapter(self): return lambda text: RstTools.make_chapter(pystache.render(text, self)) @@ -245,19 +252,38 @@ class SphinxPage(SphinxPart): class IndexPage(SphinxPage): - def __init__(self, lang, langs): - SphinxPage.__init__(self, lang, langs, 'index.rst') - self.tocEntries = [] - - def add_class_entry(self, _class): - self.tocEntries.append({'entryName': SphinxPage._classname_to_filename(_class.name)}) + def __init__(self, lang, filename): + SphinxPage.__init__(self, lang, None, filename) + self._entries = [] + self._sorted = True + + @property + def title(self): + return RstTools.make_chapter("{0} API".format(self.lang.displayName)) + + @property + def dir(self): + return self.lang.langCode.lower() + + @property + def entries(self): + if not self._sorted: + self._entries.sort(key=lambda x: x['filename']) + self._sorted = True + return self._entries + + def add_entry(self, filename): + self.entries.append({'filename': filename}) + self._sorted = False -class EnumsPage(SphinxPage): - def __init__(self, lang, langs, api): - SphinxPage.__init__(self, lang, langs, 'enums.rst') - self.namespace = api.namespace.name.translate(lang.nameTranslator) if lang.langCode != 'C' else None - self.enums = [EnumPart(enum, lang, langs, namespace=api.namespace) for enum in api.namespace.enums] +class EnumPage(SphinxPage): + def __init__(self, enum, lang, langs): + filename = SphinxPage._classname_to_filename(enum.name) + SphinxPage.__init__(self, lang, langs, filename) + namespace = enum.find_first_ancestor_by_type(abstractapi.Namespace) + self.namespace = namespace.name.translate(lang.nameTranslator) if lang.langCode != 'C' else None + self.enum = EnumPart(enum, lang, langs, namespace=namespace) class ClassPage(SphinxPage): @@ -376,20 +402,19 @@ class DocGenerator: def generate(self, outputdir): for lang in self.languages: + indexPage = IndexPage(lang, 'index.rst') subdirectory = lang.langCode.lower() directory = os.path.join(args.outputdir, subdirectory) if not os.path.exists(directory): os.mkdir(directory) - - enumsPage = EnumsPage(lang, self.languages, self.api) - enumsPage.write(directory) - - indexPage = IndexPage(lang, self.languages) - for _class in self.api.namespace.classes: - page = ClassPage(_class, lang, self.languages) + for enum in self.api.namespace.enums: + page = EnumPage(enum, lang, self.languages) page.write(directory) - indexPage.add_class_entry(_class) - + indexPage.add_entry(page.filename) + for class_ in self.api.namespace.classes: + page = ClassPage(class_, lang, self.languages) + page.write(directory) + indexPage.add_entry(page.filename) indexPage.write(directory) diff --git a/coreapi/help/doc/sphinx/index.rst b/coreapi/help/doc/sphinx/index.rst index 93d7d0a30..5a34626a7 100644 --- a/coreapi/help/doc/sphinx/index.rst +++ b/coreapi/help/doc/sphinx/index.rst @@ -7,19 +7,10 @@ Welcome to Linphone API's documentation! ======================================== .. toctree:: - :maxdepth: 1 + :maxdepth: 2 :caption: Contents: c/index.rst cpp/index.rst java/index.rst csharp/index.rst - - -Indices and tables -================== - -* :ref:`genindex` -* :ref:`modindex` -* :ref:`search` - diff --git a/coreapi/help/doc/sphinx/index_page.mustache b/coreapi/help/doc/sphinx/index_page.mustache index 2fa38ec83..f494d825e 100644 --- a/coreapi/help/doc/sphinx/index_page.mustache +++ b/coreapi/help/doc/sphinx/index_page.mustache @@ -1,19 +1,8 @@ -{{#make_section}}{{{language}}} API{{/make_section}} - -Index of classes ----------------- +{{{title}}} .. toctree:: :maxdepth: 1 - - {{#tocEntries}} - {{{entryName}}} - {{/tocEntries}} -Index of enums --------------- - -.. toctree:: - :maxdepth 1 - - enums.rst + {{#entries}} + {{{filename}}} + {{/entries}}