Skip to content

Commit

Permalink
Merge pull request #1422 from dhunstack/genrst
Browse files Browse the repository at this point in the history 
[feat] Add sidebar in algorithms reference page
  • Loading branch information
@dbogdanov
dbogdanov authored Jun 19, 2024
2 parents a94e021 + d7ea7b6 commit 30c8920
Show file tree
Hide file tree
Showing 3 changed files with 104 additions and 47 deletions.
1 change: 1 addition & 0 deletions doc/build_sphinx_doc.sh
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
9 changes: 6 additions & 3 deletions doc/sphinxdoc/conf.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
141 changes: 97 additions & 44 deletions doc/sphinxdoc/generate_reference.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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']), '']
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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, {})
Expand All @@ -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 = '''
Expand Down Expand Up @@ -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:
Expand All @@ -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
Expand Down Expand Up @@ -463,43 +489,70 @@ def write_algorithms_reference():
if len(description):
description = description[0].capitalize() + description[1:]

links = []
if std_algo:
links.append('<a class="reference internal" href="reference/std_' + algoname + '.html"><em>standard</em></a>')
if streaming_algo:
links.append('<a class="reference internal" href="reference/streaming_' + algoname + '.html"><em>streaming</em></a>')
algo_html = '<div class="algo-info">' + '<header><h3>' + algoname + '</h3></header>' + '<span>(' + ', '.join(links) + ')</span>' + '<div>' + description + '</div></div>'
algo_categories_html.setdefault(category, [])
algo_categories_html[category].append(algo_html)
############################################################
# Deprecated code for generating html file.
############################################################

# links = []
# if std_algo:
# links.append('<a class="reference internal" href="reference/std_' + algoname + '.html"><em>standard</em></a>')
# if streaming_algo:
# links.append('<a class="reference internal" href="reference/streaming_' + algoname + '.html"><em>streaming</em></a>')
# algo_html = '<div class="algo-info">' + '<header><h3>' + algoname + '</h3></header>' + '<span>(' + ', '.join(links) + ')</span>' + '<div>' + description + '</div></div>'
# algo_categories_html.setdefault(category, [])
# algo_categories_html[category].append(algo_html)

html = '''
{% extends "layout.html" %}
{% set title = "Algorithms reference" %}
{% block body %}

<div class="section" id="algorithms-reference">
<h1>Algorithms reference<a class="headerlink" href="#algorithms-reference" title="Permalink to this headline">¶</a></h1>
<p>Here is the complete list of algorithms which you can access from the Python interface.</p>
<p>The C++ interface allows access to the same algorithms, and also some more which are templated
and hence are not available in python.</p>
# html = '''
# {% extends "layout.html" %}
# {% set title = "Algorithms reference" %}
# {% block body %}

<div class="section" id="algorithms">
'''
for category in algo_categories_html:
category_id = re.sub('[^0-9a-zA-Z]+', '', category.lower())
html += '<section><h2 id=' + category_id + '>' + category + '</h2>'
html += '\n'.join(sorted(algo_categories_html[category]))
html += '</section>'
html += '''
</div>
# <div class="section" id="algorithms-reference">
# <h1>Algorithms reference<a class="headerlink" href="#algorithms-reference" title="Permalink to this headline">¶</a></h1>
# <p>Here is the complete list of algorithms which you can access from the Python interface.</p>
# <p>The C++ interface allows access to the same algorithms, and also some more which are templated
# and hence are not available in python.</p>

</div>
# <div class="section" id="algorithms">
# '''
# for category in algo_categories_html:
# category_id = re.sub('[^0-9a-zA-Z]+', '', category.lower())
# html += '<section><h2 id=' + category_id + '>' + category + '</h2>'
# html += '\n'.join(sorted(algo_categories_html[category]))
# html += '</section>'
# html += '''
# </div>

{% endblock %}
'''
# </div>

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 <reference/std_' + algoname + '>`')
if streaming_algo:
links.append(':doc:`streaming <reference/streaming_' + algoname + '>`')
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__':
Expand Down

0 comments on commit 30c8920

Please sign in to comment.