Doc generator: global table of content in the side pannel

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)

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 ------------------------------------------

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}}

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)
 
 

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`
-

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}}