diff --git a/.readthedocs.yaml b/.readthedocs.yaml index 098c5f622b..137b89c4cd 100644 --- a/.readthedocs.yaml +++ b/.readthedocs.yaml @@ -7,7 +7,7 @@ version: 2 # Build documentation in the docs/ directory with Sphinx sphinx: - builder: htmldir + builder: dirhtml configuration: doc/src/conf.py # Optionally build your docs in additional formats such as PDF and ePub @@ -15,6 +15,6 @@ formats: all # Optionally set the version of Python and requirements required to build your docs python: - version: 2 + version: 3.7 install: - requirements: doc/requirements.txt diff --git a/doc/README b/doc/README index 455de13989..e77d3db05b 100644 --- a/doc/README +++ b/doc/README @@ -42,6 +42,10 @@ For instance: $ firefox _build/html/index.html +If you want to skip automatic Doxygen XML generation, you can set: + + $ export SKIP_DOXYGEN=True + Documentation Layout -------------------- @@ -58,10 +62,10 @@ Each of these files must be referred to in the sub-system's index.rst in order t Useful Resources: ----------------- -Re-Structured Text syntax: +Re-Structured Text syntax: http://www.sphinx-doc.org/en/stable/rest.html -Paragraph-level markup: +Paragraph-level markup: http://www.sphinx-doc.org/en/stable/markup/para.html Inline markup: diff --git a/doc/_doxygen/ODIN_II.dox b/doc/_doxygen/ODIN_II.dox new file mode 100644 index 0000000000..9d686ac30a --- /dev/null +++ b/doc/_doxygen/ODIN_II.dox @@ -0,0 +1,13 @@ +PROJECT_NAME = "Verilog to Routing - ODIN_II" +OUTPUT_DIRECTORY = ../_build/doxygen/ODIN_II +FULL_PATH_NAMES = NO +OPTIMIZE_OUTPUT_FOR_C = YES +EXTRACT_ALL = YES +EXTRACT_PRIVATE = YES +EXTRACT_STATIC = YES +WARN_IF_UNDOCUMENTED = NO +INPUT = ../../ODIN_II +RECURSIVE = YES +GENERATE_HTML = NO +GENERATE_LATEX = NO +GENERATE_XML = YES diff --git a/doc/_doxygen/abc.dox b/doc/_doxygen/abc.dox new file mode 100644 index 0000000000..a556d3958c --- /dev/null +++ b/doc/_doxygen/abc.dox @@ -0,0 +1,13 @@ +PROJECT_NAME = "Verilog to Routing - ABC" +OUTPUT_DIRECTORY = ../_build/doxygen/abc +FULL_PATH_NAMES = NO +OPTIMIZE_OUTPUT_FOR_C = YES +EXTRACT_ALL = YES +EXTRACT_PRIVATE = YES +EXTRACT_STATIC = YES +WARN_IF_UNDOCUMENTED = NO +INPUT = ../../abc +RECURSIVE = YES +GENERATE_HTML = NO +GENERATE_LATEX = NO +GENERATE_XML = YES diff --git a/doc/_doxygen/ace2.dox b/doc/_doxygen/ace2.dox new file mode 100644 index 0000000000..900ac0fb5c --- /dev/null +++ b/doc/_doxygen/ace2.dox @@ -0,0 +1,13 @@ +PROJECT_NAME = "Verilog to Routing - ACE2" +OUTPUT_DIRECTORY = ../_build/doxygen/ace2 +FULL_PATH_NAMES = NO +OPTIMIZE_OUTPUT_FOR_C = YES +EXTRACT_ALL = YES +EXTRACT_PRIVATE = YES +EXTRACT_STATIC = YES +WARN_IF_UNDOCUMENTED = NO +INPUT = ../../ace2 +RECURSIVE = YES +GENERATE_HTML = NO +GENERATE_LATEX = NO +GENERATE_XML = YES diff --git a/doc/_doxygen/blifexplorer.dox b/doc/_doxygen/blifexplorer.dox new file mode 100644 index 0000000000..d3df54bfe0 --- /dev/null +++ b/doc/_doxygen/blifexplorer.dox @@ -0,0 +1,13 @@ +PROJECT_NAME = "Verilog to Routing - blifexplorer" +OUTPUT_DIRECTORY = ../_build/doxygen/blifexplorer +FULL_PATH_NAMES = NO +OPTIMIZE_OUTPUT_FOR_C = YES +EXTRACT_ALL = YES +EXTRACT_PRIVATE = YES +EXTRACT_STATIC = YES +WARN_IF_UNDOCUMENTED = NO +INPUT = ../../blifexplorer +RECURSIVE = YES +GENERATE_HTML = NO +GENERATE_LATEX = NO +GENERATE_XML = YES diff --git a/doc/_doxygen/vpr.dox b/doc/_doxygen/vpr.dox new file mode 100644 index 0000000000..5d2933b529 --- /dev/null +++ b/doc/_doxygen/vpr.dox @@ -0,0 +1,13 @@ +PROJECT_NAME = "Verilog to Routing - VPR" +OUTPUT_DIRECTORY = ../_build/doxygen/vpr +FULL_PATH_NAMES = NO +OPTIMIZE_OUTPUT_FOR_C = YES +EXTRACT_ALL = YES +EXTRACT_PRIVATE = YES +EXTRACT_STATIC = YES +WARN_IF_UNDOCUMENTED = NO +INPUT = ../../vpr +RECURSIVE = YES +GENERATE_HTML = NO +GENERATE_LATEX = NO +GENERATE_XML = YES diff --git a/doc/requirements.txt b/doc/requirements.txt index aa6547f6b3..7f182099e1 100644 --- a/doc/requirements.txt +++ b/doc/requirements.txt @@ -2,6 +2,7 @@ # used by Read The Docs to install python required # modules with pip. +Sphinx==3.0 sphinx_rtd_theme # Support custom domains @@ -28,3 +29,6 @@ docutils>=0.14 #Generates a project specific 404 (page not found) page sphinx-notfound-page + +#API Documentation +breathe diff --git a/doc/src/conf.py b/doc/src/conf.py index 764d7a9231..90c08fc284 100644 --- a/doc/src/conf.py +++ b/doc/src/conf.py @@ -15,6 +15,8 @@ import sys import os import shlex +import shutil +import subprocess # Markdown support import recommonmark @@ -47,7 +49,7 @@ # -- General configuration ------------------------------------------------ # If your documentation needs a minimal Sphinx version, state it here. -#needs_sphinx = '1.0' +needs_sphinx = '3.0' # Add any Sphinx extension module names here, as strings. They can be # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom @@ -55,6 +57,8 @@ extensions = [ 'sphinx.ext.todo', 'sphinx.ext.mathjax', + 'sphinx.ext.imgmath', + 'breathe', 'notfound.extension', 'sphinx_markdown_tables', 'sdcdomain', @@ -65,7 +69,7 @@ if have_sphinxcontrib_bibtex: extensions.append('sphinxcontrib.bibtex') else: - print "Warning: Could not find sphinxcontrib.bibtex for managing citations, attempting to build anyway..." + print("Warning: Could not find sphinxcontrib.bibtex for managing citations, attempting to build anyway...") # Add any paths that contain templates here, relative to this directory. templates_path = [] @@ -86,9 +90,9 @@ master_doc = 'index' # General information about the project. -project = u'Verilog-to-Routing' -copyright = u'2016, VTR Developers' -author = u'VTR Developers' +project = 'Verilog-to-Routing' +copyright = '2016, VTR Developers' +author = 'VTR Developers' # The version info for the project you're documenting, acts as replacement for # |version| and |release|, also used in various other places throughout the @@ -268,8 +272,8 @@ # (source start file, target name, title, # author, documentclass [howto, manual, or own class]). latex_documents = [ - (master_doc, 'Verilog-to-Routing.tex', u'Verilog-to-Routing Documentation', - u'VTR Developers', 'manual'), + (master_doc, 'Verilog-to-Routing.tex', 'Verilog-to-Routing Documentation', + 'VTR Developers', 'manual'), ] # The name of an image file (relative to this directory) to place at the top of @@ -292,27 +296,25 @@ # If false, no module index is generated. #latex_domain_indices = True - # -- Options for manual page output --------------------------------------- # One entry per manual page. List of tuples # (source start file, name, description, authors, manual section). man_pages = [ - (master_doc, 'verilog-to-routing', u'Verilog-to-Routing Documentation', + (master_doc, 'verilog-to-routing', 'Verilog-to-Routing Documentation', [author], 1) ] # If true, show URL addresses after external links. #man_show_urls = False - # -- Options for Texinfo output ------------------------------------------- # Grouping the document tree into Texinfo files. List of tuples # (source start file, target name, title, author, # dir menu entry, description, category) texinfo_documents = [ - (master_doc, 'Verilog-to-Routing', u'Verilog-to-Routing Documentation', + (master_doc, 'Verilog-to-Routing', 'Verilog-to-Routing Documentation', author, 'Verilog-to-Routing', 'One line description of project.', 'Miscellaneous'), ] @@ -342,6 +344,26 @@ ''', } +if shutil.which("doxygen"): + breathe_projects = { + "vpr" : "../_build/doxygen/vpr/xml", + "abc" : "../_build/doxygen/abc/xml", + "ace2" : "../_build/doxygen/ace2/xml", + "ODIN_II" : "../_build/doxygen/ODIN_II/xml", + "blifexplorer" : "../_build/doxygen/blifexplorer/xml", + } + breathe_default_project = "vpr" + + if not os.environ.get('SKIP_DOXYGEN', None) == 'True': + for prjname, prjdir in breathe_projects.items(): + print("Generating doxygen files for {}...".format(prjname)) + os.makedirs(prjdir, exist_ok=True) + cmd = "cd ../_doxygen && doxygen {}.dox".format(prjname) + subprocess.call(cmd, shell=True) + else: + for prjname, prjdir in breathe_projects.items(): + assert os.path.exists(prjdir) == True, "Regenerate doxygen XML for {}".format(prjname) + def setup(app): github_code_repo = 'https://github.com/verilog-to-routing/vtr-verilog-to-routing/' github_code_branch = 'blob/master/'