espressif/esp-idf
1
0
Fork 1
mirror of https://github.com/espressif/esp-idf.git synced 2025-11-04 09:01:40 +01:00
Code Issues Packages Projects Releases Wiki Activity
Files
6cb271c20b87aa7c9c7ecf0533232b60c8376493
esp-idf/docs/link-roles.py

75 lines
2.9 KiB
Python
Raw Normal View History

docs: use custom roles to generate GitHub links This change replaces direct links to GitHub master branch with auto-generated links using docutils custom roles. These auto-generated links point to the tree or blob for the git commit ID (or tag) of the repository. This is needed to ensure that links don’t become broken when files in master branch are moved around or deleted. The following roles are introduced: - :idf:`path` - points to directory inside ESP-IDF - :idf_blob:`path` - points to file inside ESP-IDF - :idf_raw:`path` - points to raw view of the file inside ESP-IDF - :component:`path` - points to directory inside ESP-IDF components dir - :component_blob:`path` - points to file inside ESP-IDF components dir - :component_raw:`path` - points to raw view of the file inside ESP-IDF components dir - :example:`path` - points to directory inside ESP-IDF examples dir - :example_blob:`path` - points to file inside ESP-IDF examples dir - :example_raw:`path` - points to raw view of the file inside ESP-IDF examples dir A check is added to the CI build script, which searches RST files for presence of hard-coded links (identified by tree/master, blob/master, or raw/master part of the URL). This check can be run manually: cd docs && make gh-linkcheck Additionally, Sphinx linkcheck build type is used to create new CI test, which check for broken links. This test has to be triggered explicitly, because including it in normal build process (when the commit is not yet deployed to Github) will not work. It can be triggered in a regular fashion using a combination of cron and Curl, similar to stress tests.
2017-01-19 16:16:06 +08:00
# based on http://protips.readthedocs.io/link-roles.html
docs: Make the Python scripts Python 2&3 compatible
2018-09-07 13:46:50 +02:00
from __future__ import print_function
from __future__ import unicode_literals
Custom link roles have been extended to provide an option of displaying some text where originally a bare link is rendered
2018-01-17 20:01:36 +01:00
import re
Implemented docutils custom role that renders a link to current documentation page on Read The Docs in another language version Provided documentation of the role.
2018-03-16 02:28:58 +08:00
import os
docs: use custom roles to generate GitHub links This change replaces direct links to GitHub master branch with auto-generated links using docutils custom roles. These auto-generated links point to the tree or blob for the git commit ID (or tag) of the repository. This is needed to ensure that links don’t become broken when files in master branch are moved around or deleted. The following roles are introduced: - :idf:`path` - points to directory inside ESP-IDF - :idf_blob:`path` - points to file inside ESP-IDF - :idf_raw:`path` - points to raw view of the file inside ESP-IDF - :component:`path` - points to directory inside ESP-IDF components dir - :component_blob:`path` - points to file inside ESP-IDF components dir - :component_raw:`path` - points to raw view of the file inside ESP-IDF components dir - :example:`path` - points to directory inside ESP-IDF examples dir - :example_blob:`path` - points to file inside ESP-IDF examples dir - :example_raw:`path` - points to raw view of the file inside ESP-IDF examples dir A check is added to the CI build script, which searches RST files for presence of hard-coded links (identified by tree/master, blob/master, or raw/master part of the URL). This check can be run manually: cd docs && make gh-linkcheck Additionally, Sphinx linkcheck build type is used to create new CI test, which check for broken links. This test has to be triggered explicitly, because including it in normal build process (when the commit is not yet deployed to Github) will not work. It can be triggered in a regular fashion using a combination of cron and Curl, similar to stress tests.
2017-01-19 16:16:06 +08:00
from docutils import nodes
docs: speed up incremental builds On each documentation build (‘make html’), doxygen regenerates XML files. In addition to that, gen-dxd.py regenerates API reference files under _build/inc/. This results in Sphinx flagging about half of the input files as modified, and incremental builds taking long time. With this change, XML files generated by Doxygen are copied into docs/xml_in directory only when they are changed. Breathe is pointed to docs/xml_in directory instead of docs/xml. In addition to that, gen-dxd.py is modified to only write to the output file when contents change. Overall, incremental build time (with no source files changed) is reduced from ~7 minutes to ~8 seconds (on a particular OS X computer). Due to the way Breathe includes Doxygen XML files, there is still going to be a massive rebuild every time functions, enums, macros, structures are added or removed from the header files scanned by Doxygen, but at least individual .rst files can be edited at a much faster pace.
2018-03-05 20:12:52 +08:00
from local_util import run_cmd_get_output
docs: use custom roles to generate GitHub links This change replaces direct links to GitHub master branch with auto-generated links using docutils custom roles. These auto-generated links point to the tree or blob for the git commit ID (or tag) of the repository. This is needed to ensure that links don’t become broken when files in master branch are moved around or deleted. The following roles are introduced: - :idf:`path` - points to directory inside ESP-IDF - :idf_blob:`path` - points to file inside ESP-IDF - :idf_raw:`path` - points to raw view of the file inside ESP-IDF - :component:`path` - points to directory inside ESP-IDF components dir - :component_blob:`path` - points to file inside ESP-IDF components dir - :component_raw:`path` - points to raw view of the file inside ESP-IDF components dir - :example:`path` - points to directory inside ESP-IDF examples dir - :example_blob:`path` - points to file inside ESP-IDF examples dir - :example_raw:`path` - points to raw view of the file inside ESP-IDF examples dir A check is added to the CI build script, which searches RST files for presence of hard-coded links (identified by tree/master, blob/master, or raw/master part of the URL). This check can be run manually: cd docs && make gh-linkcheck Additionally, Sphinx linkcheck build type is used to create new CI test, which check for broken links. This test has to be triggered explicitly, because including it in normal build process (when the commit is not yet deployed to Github) will not work. It can be triggered in a regular fashion using a combination of cron and Curl, similar to stress tests.
2017-01-19 16:16:06 +08:00
docs: Correct Python coding style
2018-12-01 09:25:08 +01:00
docs: use custom roles to generate GitHub links This change replaces direct links to GitHub master branch with auto-generated links using docutils custom roles. These auto-generated links point to the tree or blob for the git commit ID (or tag) of the repository. This is needed to ensure that links don’t become broken when files in master branch are moved around or deleted. The following roles are introduced: - :idf:`path` - points to directory inside ESP-IDF - :idf_blob:`path` - points to file inside ESP-IDF - :idf_raw:`path` - points to raw view of the file inside ESP-IDF - :component:`path` - points to directory inside ESP-IDF components dir - :component_blob:`path` - points to file inside ESP-IDF components dir - :component_raw:`path` - points to raw view of the file inside ESP-IDF components dir - :example:`path` - points to directory inside ESP-IDF examples dir - :example_blob:`path` - points to file inside ESP-IDF examples dir - :example_raw:`path` - points to raw view of the file inside ESP-IDF examples dir A check is added to the CI build script, which searches RST files for presence of hard-coded links (identified by tree/master, blob/master, or raw/master part of the URL). This check can be run manually: cd docs && make gh-linkcheck Additionally, Sphinx linkcheck build type is used to create new CI test, which check for broken links. This test has to be triggered explicitly, because including it in normal build process (when the commit is not yet deployed to Github) will not work. It can be triggered in a regular fashion using a combination of cron and Curl, similar to stress tests.
2017-01-19 16:16:06 +08:00
def get_github_rev():
path = run_cmd_get_output('git rev-parse --short HEAD')
tag = run_cmd_get_output('git describe --exact-match')
docs: Make the Python scripts Python 2&3 compatible
2018-09-07 13:46:50 +02:00
print('Git commit ID: ', path)
docs: use custom roles to generate GitHub links This change replaces direct links to GitHub master branch with auto-generated links using docutils custom roles. These auto-generated links point to the tree or blob for the git commit ID (or tag) of the repository. This is needed to ensure that links don’t become broken when files in master branch are moved around or deleted. The following roles are introduced: - :idf:`path` - points to directory inside ESP-IDF - :idf_blob:`path` - points to file inside ESP-IDF - :idf_raw:`path` - points to raw view of the file inside ESP-IDF - :component:`path` - points to directory inside ESP-IDF components dir - :component_blob:`path` - points to file inside ESP-IDF components dir - :component_raw:`path` - points to raw view of the file inside ESP-IDF components dir - :example:`path` - points to directory inside ESP-IDF examples dir - :example_blob:`path` - points to file inside ESP-IDF examples dir - :example_raw:`path` - points to raw view of the file inside ESP-IDF examples dir A check is added to the CI build script, which searches RST files for presence of hard-coded links (identified by tree/master, blob/master, or raw/master part of the URL). This check can be run manually: cd docs && make gh-linkcheck Additionally, Sphinx linkcheck build type is used to create new CI test, which check for broken links. This test has to be triggered explicitly, because including it in normal build process (when the commit is not yet deployed to Github) will not work. It can be triggered in a regular fashion using a combination of cron and Curl, similar to stress tests.
2017-01-19 16:16:06 +08:00
if len(tag):
docs: Make the Python scripts Python 2&3 compatible
2018-09-07 13:46:50 +02:00
print('Git tag: ', tag)
docs: use custom roles to generate GitHub links This change replaces direct links to GitHub master branch with auto-generated links using docutils custom roles. These auto-generated links point to the tree or blob for the git commit ID (or tag) of the repository. This is needed to ensure that links don’t become broken when files in master branch are moved around or deleted. The following roles are introduced: - :idf:`path` - points to directory inside ESP-IDF - :idf_blob:`path` - points to file inside ESP-IDF - :idf_raw:`path` - points to raw view of the file inside ESP-IDF - :component:`path` - points to directory inside ESP-IDF components dir - :component_blob:`path` - points to file inside ESP-IDF components dir - :component_raw:`path` - points to raw view of the file inside ESP-IDF components dir - :example:`path` - points to directory inside ESP-IDF examples dir - :example_blob:`path` - points to file inside ESP-IDF examples dir - :example_raw:`path` - points to raw view of the file inside ESP-IDF examples dir A check is added to the CI build script, which searches RST files for presence of hard-coded links (identified by tree/master, blob/master, or raw/master part of the URL). This check can be run manually: cd docs && make gh-linkcheck Additionally, Sphinx linkcheck build type is used to create new CI test, which check for broken links. This test has to be triggered explicitly, because including it in normal build process (when the commit is not yet deployed to Github) will not work. It can be triggered in a regular fashion using a combination of cron and Curl, similar to stress tests.
2017-01-19 16:16:06 +08:00
path = tag
return path
docs: Correct Python coding style
2018-12-01 09:25:08 +01:00
docs: use custom roles to generate GitHub links This change replaces direct links to GitHub master branch with auto-generated links using docutils custom roles. These auto-generated links point to the tree or blob for the git commit ID (or tag) of the repository. This is needed to ensure that links don’t become broken when files in master branch are moved around or deleted. The following roles are introduced: - :idf:`path` - points to directory inside ESP-IDF - :idf_blob:`path` - points to file inside ESP-IDF - :idf_raw:`path` - points to raw view of the file inside ESP-IDF - :component:`path` - points to directory inside ESP-IDF components dir - :component_blob:`path` - points to file inside ESP-IDF components dir - :component_raw:`path` - points to raw view of the file inside ESP-IDF components dir - :example:`path` - points to directory inside ESP-IDF examples dir - :example_blob:`path` - points to file inside ESP-IDF examples dir - :example_raw:`path` - points to raw view of the file inside ESP-IDF examples dir A check is added to the CI build script, which searches RST files for presence of hard-coded links (identified by tree/master, blob/master, or raw/master part of the URL). This check can be run manually: cd docs && make gh-linkcheck Additionally, Sphinx linkcheck build type is used to create new CI test, which check for broken links. This test has to be triggered explicitly, because including it in normal build process (when the commit is not yet deployed to Github) will not work. It can be triggered in a regular fashion using a combination of cron and Curl, similar to stress tests.
2017-01-19 16:16:06 +08:00
def setup(app):
rev = get_github_rev()
Implemented docutils custom role that renders a link to current documentation page on Read The Docs in another language version Provided documentation of the role.
2018-03-16 02:28:58 +08:00
# links to files or folders on the GitHub
baseurl = 'https://github.com/espressif/esp-idf'
docs: use custom roles to generate GitHub links This change replaces direct links to GitHub master branch with auto-generated links using docutils custom roles. These auto-generated links point to the tree or blob for the git commit ID (or tag) of the repository. This is needed to ensure that links don’t become broken when files in master branch are moved around or deleted. The following roles are introduced: - :idf:`path` - points to directory inside ESP-IDF - :idf_blob:`path` - points to file inside ESP-IDF - :idf_raw:`path` - points to raw view of the file inside ESP-IDF - :component:`path` - points to directory inside ESP-IDF components dir - :component_blob:`path` - points to file inside ESP-IDF components dir - :component_raw:`path` - points to raw view of the file inside ESP-IDF components dir - :example:`path` - points to directory inside ESP-IDF examples dir - :example_blob:`path` - points to file inside ESP-IDF examples dir - :example_raw:`path` - points to raw view of the file inside ESP-IDF examples dir A check is added to the CI build script, which searches RST files for presence of hard-coded links (identified by tree/master, blob/master, or raw/master part of the URL). This check can be run manually: cd docs && make gh-linkcheck Additionally, Sphinx linkcheck build type is used to create new CI test, which check for broken links. This test has to be triggered explicitly, because including it in normal build process (when the commit is not yet deployed to Github) will not work. It can be triggered in a regular fashion using a combination of cron and Curl, similar to stress tests.
2017-01-19 16:16:06 +08:00
app.add_role('idf', autolink('{}/tree/{}/%s'.format(baseurl, rev)))
app.add_role('idf_file', autolink('{}/blob/{}/%s'.format(baseurl, rev)))
app.add_role('idf_raw', autolink('{}/raw/{}/%s'.format(baseurl, rev)))
app.add_role('component', autolink('{}/tree/{}/components/%s'.format(baseurl, rev)))
app.add_role('component_file', autolink('{}/blob/{}/components/%s'.format(baseurl, rev)))
app.add_role('component_raw', autolink('{}/raw/{}/components/%s'.format(baseurl, rev)))
app.add_role('example', autolink('{}/tree/{}/examples/%s'.format(baseurl, rev)))
app.add_role('example_file', autolink('{}/blob/{}/examples/%s'.format(baseurl, rev)))
app.add_role('example_raw', autolink('{}/raw/{}/examples/%s'.format(baseurl, rev)))
Implemented docutils custom role that renders a link to current documentation page on Read The Docs in another language version Provided documentation of the role.
2018-03-16 02:28:58 +08:00
# link to the current documentation file in specific language version
on_rtd = os.environ.get('READTHEDOCS', None) == 'True'
if on_rtd:
# provide RTD specific commit identification to be included in the link
tag_rev = 'latest'
if (run_cmd_get_output('git rev-parse --short HEAD') != rev):
tag_rev = rev
else:
docs: Correct Python coding style
2018-12-01 09:25:08 +01:00
# if not on the RTD then provide generic identification
Implemented docutils custom role that renders a link to current documentation page on Read The Docs in another language version Provided documentation of the role.
2018-03-16 02:28:58 +08:00
tag_rev = run_cmd_get_output('git describe --always')
app.add_role('link_to_translation', crosslink('%s../../%s/{}/%s.html'.format(tag_rev)))
docs: Correct Python coding style
2018-12-01 09:25:08 +01:00
docs: use custom roles to generate GitHub links This change replaces direct links to GitHub master branch with auto-generated links using docutils custom roles. These auto-generated links point to the tree or blob for the git commit ID (or tag) of the repository. This is needed to ensure that links don’t become broken when files in master branch are moved around or deleted. The following roles are introduced: - :idf:`path` - points to directory inside ESP-IDF - :idf_blob:`path` - points to file inside ESP-IDF - :idf_raw:`path` - points to raw view of the file inside ESP-IDF - :component:`path` - points to directory inside ESP-IDF components dir - :component_blob:`path` - points to file inside ESP-IDF components dir - :component_raw:`path` - points to raw view of the file inside ESP-IDF components dir - :example:`path` - points to directory inside ESP-IDF examples dir - :example_blob:`path` - points to file inside ESP-IDF examples dir - :example_raw:`path` - points to raw view of the file inside ESP-IDF examples dir A check is added to the CI build script, which searches RST files for presence of hard-coded links (identified by tree/master, blob/master, or raw/master part of the URL). This check can be run manually: cd docs && make gh-linkcheck Additionally, Sphinx linkcheck build type is used to create new CI test, which check for broken links. This test has to be triggered explicitly, because including it in normal build process (when the commit is not yet deployed to Github) will not work. It can be triggered in a regular fashion using a combination of cron and Curl, similar to stress tests.
2017-01-19 16:16:06 +08:00
def autolink(pattern):
def role(name, rawtext, text, lineno, inliner, options={}, content=[]):
docs: Correct Python coding style
2018-12-01 09:25:08 +01:00
m = re.search('(.*)\s*<(.*)>', text) # noqa: W605 - regular expression
Custom link roles have been extended to provide an option of displaying some text where originally a bare link is rendered
2018-01-17 20:01:36 +01:00
if m:
link_text = m.group(1)
link = m.group(2)
else:
link_text = text
link = text
url = pattern % (link,)
node = nodes.reference(rawtext, link_text, refuri=url, **options)
docs: use custom roles to generate GitHub links This change replaces direct links to GitHub master branch with auto-generated links using docutils custom roles. These auto-generated links point to the tree or blob for the git commit ID (or tag) of the repository. This is needed to ensure that links don’t become broken when files in master branch are moved around or deleted. The following roles are introduced: - :idf:`path` - points to directory inside ESP-IDF - :idf_blob:`path` - points to file inside ESP-IDF - :idf_raw:`path` - points to raw view of the file inside ESP-IDF - :component:`path` - points to directory inside ESP-IDF components dir - :component_blob:`path` - points to file inside ESP-IDF components dir - :component_raw:`path` - points to raw view of the file inside ESP-IDF components dir - :example:`path` - points to directory inside ESP-IDF examples dir - :example_blob:`path` - points to file inside ESP-IDF examples dir - :example_raw:`path` - points to raw view of the file inside ESP-IDF examples dir A check is added to the CI build script, which searches RST files for presence of hard-coded links (identified by tree/master, blob/master, or raw/master part of the URL). This check can be run manually: cd docs && make gh-linkcheck Additionally, Sphinx linkcheck build type is used to create new CI test, which check for broken links. This test has to be triggered explicitly, because including it in normal build process (when the commit is not yet deployed to Github) will not work. It can be triggered in a regular fashion using a combination of cron and Curl, similar to stress tests.
2017-01-19 16:16:06 +08:00
return [node], []
return role
Implemented docutils custom role that renders a link to current documentation page on Read The Docs in another language version Provided documentation of the role.
2018-03-16 02:28:58 +08:00
docs: Correct Python coding style
2018-12-01 09:25:08 +01:00
Implemented docutils custom role that renders a link to current documentation page on Read The Docs in another language version Provided documentation of the role.
2018-03-16 02:28:58 +08:00
def crosslink(pattern):
def role(name, rawtext, text, lineno, inliner, options={}, content=[]):
(language, link_text) = text.split(':')
docname = inliner.document.settings.env.docname
doc_path = inliner.document.settings.env.doc2path(docname, None, None)
docs: Correct Python coding style
2018-12-01 09:25:08 +01:00
return_path = '../' * doc_path.count('/')
Implemented docutils custom role that renders a link to current documentation page on Read The Docs in another language version Provided documentation of the role.
2018-03-16 02:28:58 +08:00
url = pattern % (return_path, language, docname)
node = nodes.reference(rawtext, link_text, refuri=url, **options)
return [node], []
return role
Reference in New Issue Copy Permalink