Add API documentation

.gitignore

@@ -1 +1,2 @@
 /_build
+/apidoc

.gitmodules

@@ -0,0 +1,4 @@
+[submodule "code/spoofax"]
+	path = code/spoofax
+	url = https://github.com/metaborg/spoofax.git
+	branch = master

Makefile

@@ -6,6 +6,7 @@ SPHINXOPTS    =
 SPHINXBUILD   = sphinx-build
 PAPER         =
 BUILDDIR      = _build
+APIDOC        = 0
 
 # User-friendly check for sphinx-build
 ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1)
@@ -15,7 +16,8 @@ endif
 # Internal variables.
 PAPEROPT_a4     = -D latex_paper_size=a4
 PAPEROPT_letter = -D latex_paper_size=letter
-ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
+APIDOCOPT       = -D make_apidoc=$(APIDOC)
+ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(APIDOCOPT) $(SPHINXOPTS) .
 # the i18n builder cannot share the environment and doctrees with the others
 I18NSPHINXOPTS  = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
 
@@ -50,6 +52,7 @@ help:
 .PHONY: clean
 clean:
 	rm -rf $(BUILDDIR)/*
+	rm -rf apidoc/*
 
 .PHONY: html
 html:

README.md

@@ -1,4 +1,4 @@
-# Spoofax Documentation
+# Spoofax documentation
 
 This repository contains the Spoofax documentation, made with [Sphinx](http://www.sphinx-doc.org/en/stable/) in the [Read The Docs](https://docs.readthedocs.org/en/latest/index.html) style of documentation.
 
@@ -9,12 +9,41 @@ When a commit to this repository is made, it will automatically [build and updat
 
 To build the documentation, use the Makefile:
 
+```bash
+make html
 ```
+
+which will generate HTML documentation into `_build/html` with `_build/html/index.html` as the main page.
+
+Sphinx does incremental building if possible. If your changes are not being built for some reason, use the `clean` target:
+
+```bash
 make clean html
 ```
 
-which will generate HTML documentation into `_build/html` with `_build/html/index.html` as the main page.
-Use the `latexpdf` target to build a PDF version of the documentation, and `epub` for an e-book (book format with resizable text, for tablets and e-readers) build.
+### Other targets
+
+* `latexpdf` for a PDF version (via latex) of the documentation. A working latex distribution is required.
+* `epub` for an epub version, an e-book format with resizable text, for tablets and e-readers.
+* `singlehtml` for single page HTML documentation.
+* `text` for plain-text documentation.
+* `help` for a list of all other targets.
+
+### Generated API documentation
+
+Java API documentation is generated from submodules in the `code` directory.
+Make sure all submodules are checked out and up to date by running:
+
+```bash
+git submodule update --init --remote --recursive
+```
+
+By default, generated API docs are not built when building the documentation, because it can take several minutes to generate and render them.
+To generate API docs, pass `APIDOC=1` to make:
+
+```bash
+make html APIDOC=1
+```
 
 ## Requirements
 

conf.py

@@ -15,6 +15,7 @@
 
 import sys
 import os
+import subprocess
 
 import recommonmark
 from recommonmark.parser import CommonMarkParser
@@ -36,6 +37,7 @@
 # ones.
 extensions = [
   'sphinx.ext.todo',
+  'javasphinx'
 ]
 
 # Add any paths that contain templates here, relative to this directory.
@@ -86,7 +88,7 @@
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
-exclude_patterns = ['_build', 'notes', 'README.md']
+exclude_patterns = ['_build', 'notes', 'code', 'README.md']
 
 # The reST default role (used for this markup: `text`) to use for all
 # documents.
@@ -370,7 +372,7 @@
 # If false, no index is generated.
 #epub_use_index = True
 
-# -- Setup ------------------------------------------------------------------------
+# -- Lexers ------------------------------------------------------------------------
 
 import re
 from pygments.lexer import RegexLexer, words
@@ -517,9 +519,29 @@ class EntityLexer(RegexLexer):
     ],
   }
 
+# -- API doc ------------------------------------------------------------------------
+
+def make_apidoc(app):
+  if not app.config.make_apidoc:
+    return
+  sources = {
+    'org.metaborg.core'              : 'code/spoofax/org.metaborg.core/src/main/java/'
+  , 'org.metaborg.spoofax.core'      : 'code/spoofax/org.metaborg.spoofax.core/src/main/java/'
+  , 'org.metaborg.meta.core'         : 'code/spoofax/org.metaborg.meta.core/src/main/java/'
+  , 'org.metaborg.spoofax.meta.core' : 'code/spoofax/org.metaborg.spoofax.meta.core/src/main/java/'
+  }
+  for dest, src in sources.items():
+    cur_dir = os.path.abspath(os.path.dirname(__file__))
+    output_path = os.path.join(cur_dir, 'apidoc', dest)
+    cmd_path = 'javasphinx-apidoc'
+    if hasattr(sys, 'real_prefix'):  # Check to see if we are in a virtualenv, if we are, assemble the path manually
+      cmd_path = os.path.abspath(os.path.join(sys.prefix, 'bin', 'javasphinx-apidoc'))
+    subprocess.check_call([cmd_path, '-f', '-o', output_path, src])
+
 # -- Setup ------------------------------------------------------------------------
 
 def setup(app):
+  app.add_config_value('make_apidoc', on_rtd, 'html') # Default value on_rtd such that API docs are built on RTD
   app.add_config_value('recommonmark_config', {}, 'env')
   app.add_transform(AutoStructify)
   app.add_stylesheet("custom.css")
@@ -529,3 +551,4 @@ def setup(app):
   app.add_lexer("sdf3", SDF3Lexer())
   app.add_lexer("nabl", NaBLLexer())
   app.add_lexer("entity", EntityLexer())
+  app.connect('builder-inited', make_apidoc)

make.bat

@@ -6,10 +6,11 @@ if "%SPHINXBUILD%" == "" (
 	set SPHINXBUILD=sphinx-build
 )
 set BUILDDIR=_build
+set APIDOC=0
 set ALLSPHINXOPTS=-d %BUILDDIR%/doctrees %SPHINXOPTS% .
 set I18NSPHINXOPTS=%SPHINXOPTS% .
 if NOT "%PAPER%" == "" (
-	set ALLSPHINXOPTS=-D latex_paper_size=%PAPER% %ALLSPHINXOPTS%
+	set ALLSPHINXOPTS=-D latex_paper_size=%PAPER% %ALLSPHINXOPTS% -D make_apidoc=%APIDOC%
 	set I18NSPHINXOPTS=-D latex_paper_size=%PAPER% %I18NSPHINXOPTS%
 )
 

requirements.txt

@@ -3,3 +3,4 @@ sphinx-autobuild>=0.6.0
 recommonmark>=0.4.0
 sphinx_rtd_theme>=0.1.9
 pygments>=2.1.3
+javasphinx>=0.9.13

source/core/api.rst

@@ -0,0 +1,17 @@
+===============
+API Reference
+===============
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Language Runtime
+
+   MetaBorg Core <../../apidoc/org.metaborg.core/packages>
+   Spoofax Core <../../apidoc/org.metaborg.spoofax.core/packages>
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Language Development Runtime
+
+   MetaBorg Meta Core <../../apidoc/org.metaborg.meta.core/packages>
+   Spoofax Meta Core <../../apidoc/org.metaborg.spoofax.meta.core/packages>