Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

[feat] Add sidebar in algorithms reference page #1422

Merged
merged 1 commit into from
Jun 19, 2024
Merged

[feat] Add sidebar in algorithms reference page #1422

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions doc/build_sphinx_doc.sh
View file
Open in desktop
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
Open in desktop
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
Open in desktop
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
Loading