diff --git a/doc/build_sphinx_doc.sh b/doc/build_sphinx_doc.sh index 906ab83f4..f41e4b6f4 100755 --- a/doc/build_sphinx_doc.sh +++ b/doc/build_sphinx_doc.sh @@ -37,6 +37,7 @@ pandoc ../../FAQ.md -o FAQ.rst pandoc research_papers.md -o research_papers.rst jupyter nbconvert ../../src/examples/python/*.ipynb --to rst --output-dir . +make clean make html # remove generated algorithm reference rst and temporary html files diff --git a/doc/sphinxdoc/conf.py b/doc/sphinxdoc/conf.py index df3f9b2e6..217458fe3 100644 --- a/doc/sphinxdoc/conf.py +++ b/doc/sphinxdoc/conf.py @@ -167,19 +167,22 @@ # We only want a sidebar on the models page. html_sidebars = { + # 'index': [], '**': [], + 'algorithms_reference': ['localtoc.html'], 'models': ['localtoc.html'], } # Additional templates that should be rendered to pages, maps page names to # template names. html_additional_pages = {'index': 'index.html', - 'algorithms_reference': 'algorithms_reference.html', + # 'algorithms_reference': 'algorithms_reference.html', 'applications': 'applications.html', 'documentation': 'documentation.html'} -exec(compile(open("essentia_reference.py").read(), "essentia_reference.py", 'exec')) -html_additional_pages.update(essentia_algorithms) +# Deprecating this. Generating algorithm docs directly from rst files is better for sidebar. +# exec(compile(open("essentia_reference.py").read(), "essentia_reference.py", 'exec')) +# html_additional_pages.update(essentia_algorithms) # If false, no module index is generated. #html_domain_indices = True diff --git a/doc/sphinxdoc/generate_reference.py b/doc/sphinxdoc/generate_reference.py index 44cbb5f5c..7217d1c77 100755 --- a/doc/sphinxdoc/generate_reference.py +++ b/doc/sphinxdoc/generate_reference.py @@ -176,13 +176,32 @@ def source_links(algo_doc): ## 4. Can move the URL_PREFIX to a global variable, but it looks cleaner here def doc2rst(algo_doc, sphinxsearch=False): + """ + Convert the algorithm documentation to RST format + + algo_doc: dict + Dictionary containing the algorithm documentation + sphinxsearch: bool + Flag to indicate if the RST is for sphinx search index or for HTML rendering + + Returns + ------- + str: RST formatted string + """ if sphinxsearch: # dummy rst files used to append algorithms to the sphinx HTML search - lines = [':orphan:', - '' - ] - header = 'Algorithm reference - ' + algo_doc['name'] + ' (' + algo_doc['mode'] + ')' - lines += [header, '=' * len(header), ''] +############################################################ +# Deprecated header format. +############################################################ + # lines = [':orphan:', + # '' + # ] + # header = 'Algorithm reference - ' + algo_doc['name'] + ' (' + algo_doc['mode'] + ')' + # lines += [header, '=' * len(header), ''] +############################################################ +############################################################ + lines = [ algo_doc['name'], '=' * len(algo_doc['name']), ''] + lines += [algo_doc['mode'] + ' | ' + algo_doc['category'] + ' category', ''] else: # actual rst files used to render HTMLs lines = [ algo_doc['name'], '=' * len(algo_doc['name']), ''] @@ -295,7 +314,8 @@ def write_html_doc(filename, algo_doc, layout_type): def write_algorithms_reference(): - '''Write all files necessary to have a complete algorithms reference in the sphinx doc. + ''' + Write all files necessary to have a complete algorithms reference in the sphinx doc. That includes: - write the _templates/algorithms_reference.html template - write each separate algo doc as an html template in the _templates/reference folder @@ -336,9 +356,9 @@ def write_algorithms_reference(): print('generating doc for standard algorithm: %s ...' % algoname) write_doc('reference/std_' + algoname + '.rst', algos[algoname]['standard']) - write_html_doc('_templates/reference/std_' + algoname + '.html', - algos[algoname]['standard'], - layout_type = 'std') + # write_html_doc('_templates/reference/std_' + algoname + '.html', + # algos[algoname]['standard'], + # layout_type = 'std') for algoname in streaming_algo_list: algos.setdefault(algoname, {}) @@ -347,10 +367,12 @@ def write_algorithms_reference(): print('generating doc for streaming algorithm: %s ...' % algoname) write_doc('reference/streaming_' + algoname + '.rst', algos[algoname]['streaming']) - write_html_doc('_templates/reference/streaming_' + algoname + '.html', - algos[algoname]['streaming'], - layout_type = 'streaming') + # write_html_doc('_templates/reference/streaming_' + algoname + '.html', + # algos[algoname]['streaming'], + # layout_type = 'streaming') +############################################################ +############################################################ # write the template for the std algorithms html = ''' @@ -401,6 +423,8 @@ def write_algorithms_reference(): ''' open('_templates/algo_description_layout_streaming.html', 'w').write(html) +############################################################ +############################################################ # write the essentia_reference.py file (to be included in conf.py) with open('essentia_reference.py', 'w') as algo_ref: @@ -426,9 +450,11 @@ def write_algorithms_reference(): ''') +############################################################ +############################################################ - # write the algorithms_reference.html file (main ref file) - algo_categories_html = {} + # write the algorithms_reference.rst file (main ref file) + algo_categories_rst = {} for algoname in algos: std_algo = None streaming_algo = None @@ -463,43 +489,70 @@ def write_algorithms_reference(): if len(description): description = description[0].capitalize() + description[1:] - links = [] - if std_algo: - links.append('standard') - if streaming_algo: - links.append('streaming') - algo_html = '
' + '

' + algoname + '

' + '(' + ', '.join(links) + ')' + '
' + description + '
' - algo_categories_html.setdefault(category, []) - algo_categories_html[category].append(algo_html) +############################################################ +# Deprecated code for generating html file. +############################################################ +# links = [] +# if std_algo: +# links.append('standard') +# if streaming_algo: +# links.append('streaming') +# algo_html = '
' + '

' + algoname + '

' + '(' + ', '.join(links) + ')' + '
' + description + '
' +# algo_categories_html.setdefault(category, []) +# algo_categories_html[category].append(algo_html) - html = ''' -{% extends "layout.html" %} -{% set title = "Algorithms reference" %} -{% block body %} -
-

Algorithms reference

-

Here is the complete list of algorithms which you can access from the Python interface.

-

The C++ interface allows access to the same algorithms, and also some more which are templated -and hence are not available in python.

+# html = ''' +# {% extends "layout.html" %} +# {% set title = "Algorithms reference" %} +# {% block body %} -
-''' - for category in algo_categories_html: - category_id = re.sub('[^0-9a-zA-Z]+', '', category.lower()) - html += '

' + category + '

' - html += '\n'.join(sorted(algo_categories_html[category])) - html += '
' - html += ''' -
+#
+#

Algorithms reference

+#

Here is the complete list of algorithms which you can access from the Python interface.

+#

The C++ interface allows access to the same algorithms, and also some more which are templated +# and hence are not available in python.

-
+#
+# ''' +# for category in algo_categories_html: +# category_id = re.sub('[^0-9a-zA-Z]+', '', category.lower()) +# html += '

' + category + '

' +# html += '\n'.join(sorted(algo_categories_html[category])) +# html += '
' +# html += ''' +#
-{% endblock %} -''' +#
- open('_templates/algorithms_reference.html', 'w').write(html) +# {% endblock %} +# ''' + +# open('_templates/algorithms_reference.html', 'w').write(html) + +############################################################ +############################################################ + + links = [] + if std_algo: + links.append(':doc:`standard `') + if streaming_algo: + links.append(':doc:`streaming `') + algo_rst = algoname + '\n' + '^' * len(algoname) + '\n\n' + '(' + ', '.join(links) + ')' + '\n\n' + description + '\n\n' + algo_categories_rst.setdefault(category, []) + algo_categories_rst[category].append(algo_rst) + + rst = "Algorithms reference" + \ + "\n=====================\n\n" + \ + "Here is the complete list of algorithms which you can access from the Python interface.\n\n" + \ + "The C++ interface allows access to the same algorithms, and also some more which are templated and hence are not available in python.\n\n" + for category in algo_categories_rst: + rst += category + '\n' + '-' * len(category) + '\n\n' + rst += '\n'.join(sorted(algo_categories_rst[category])) + rst += '\n' + + open('algorithms_reference.rst', 'w').write(rst) if __name__ == '__main__':