mirror of
https://github.com/espressif/esp-idf.git
synced 2025-11-04 09:01:40 +01:00
2e0f8b5a70
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.
43 lines
1.7 KiB
Python
43 lines
1.7 KiB
Python
# based on http://protips.readthedocs.io/link-roles.html
|
|
|
|
import re
|
|
from docutils import nodes
|
|
from local_util import run_cmd_get_output
|
|
|
|
def get_github_rev():
|
|
path = run_cmd_get_output('git rev-parse --short HEAD')
|
|
tag = run_cmd_get_output('git describe --exact-match')
|
|
print ('Git commit ID: ', path)
|
|
if len(tag):
|
|
print ('Git tag: ', tag)
|
|
path = tag
|
|
return path
|
|
|
|
|
|
def setup(app):
|
|
baseurl = 'https://github.com/espressif/esp-idf'
|
|
rev = get_github_rev()
|
|
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)))
|
|
|
|
def autolink(pattern):
|
|
def role(name, rawtext, text, lineno, inliner, options={}, content=[]):
|
|
m = re.search('(.*)\s*<(.*)>', text)
|
|
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)
|
|
return [node], []
|
|
return role
|