Initial support for API documentation

.readthedocs.yaml

@@ -7,14 +7,14 @@ 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
 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

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:

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

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

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

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

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

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

doc/src/conf.py

@@ -15,6 +15,8 @@
 import sys
 import os
 import shlex
+import shutil
+import subprocess
 
 # Markdown support
 import recommonmark
@@ -47,14 +49,16 @@
 # -- 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
 # ones.
 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:/verilog-to-routing/vtr-verilog-to-routing/'
  github_code_branch = 'blob/master/'