Add sphinx docs

.readthedocs.yml

@@ -0,0 +1,11 @@
+# Don't build any extra formats
+formats:
+    - htmlzip
+
+requirements_file: doc/requirements.txt
+
+build:
+    image: latest
+
+python:
+    version: 3

.travis.yml

@@ -10,8 +10,10 @@ addons:
     update: true
     packages:
      - build-essential
+     - doxygen
      - fxload
      - gnupg
+     - libenchant-dev
      - libftdi-dev
      - libreadline-dev
      - libusb-1.0-0-dev
@@ -27,23 +29,28 @@ install:
  - export PLATFORMS="$P" && echo "PLATFORMS='$PLATFORMS'"
  - export TARGETS="$T" && echo "TARGETS='$TARGETS'"
  - export FIRMWARE="$F" && echo "FIRMWARE='$FIRMWARE'"
- - $PWD/.travis/setup.sh
+ - $PWD/.travis/setup-$SCRIPT.sh
 
 script:
- - $PWD/.travis/build.sh
+ - $PWD/.travis/$SCRIPT.sh
 
 after_success:
  - $PWD/.travis/update-prebuilt-list.sh
 
 env:
   global:
+   - SCRIPT=build
    - HDMI2USB_UDEV_IGNORE=1
    - CLEAN_CHECK=1
    - PREBUILT_DIR="/tmp/HDMI2USB-firmware-prebuilt"
    # Travis reports incorrect the hosts number of processors, override to 2
    # cores.
    - JOBS=2
   matrix:
+   #--------------------------------------------
+   # Non-firmware building targets
+   #--------------------------------------------
+   - SCRIPT=docs
    #--------------------------------------------
    # Base targets
    #--------------------------------------------

.travis/docs.sh

@@ -0,0 +1,7 @@
+#! /bin/bash
+
+set -x
+set -e
+
+cd doc
+make html

.travis/setup-docs.sh

@@ -0,0 +1,9 @@
+#! /bin/bash
+
+set -x
+set -e
+
+cd doc
+make testenv
+make wiki
+make apidoc

doc/.gitignore

@@ -0,0 +1,8 @@
+.Makefile.d
+_build
+_doxygen
+_venv
+tools
+*-api
+apidoc
+wiki

doc/Makefile

@@ -0,0 +1,124 @@
+# Minimal makefile for Sphinx documentation
+
+# Use the "source" keyword which only works in bash?
+SHELL := /bin/bash
+
+# Disable make's inbuilt rules
+.SUFFIXES:
+
+# You can set these variables from the command line.
+TOPDIR        = $(realpath ..)
+BUILDDIR      = _build
+VENV_ROOT     = $(BUILDDIR)/_venv
+SPHINXOPTS    =
+SPHINXBUILD   = $(VENV_ROOT)/bin/sphinx-build
+SPHINXPROJ    = LiteXBuildEnvironment
+SOURCEDIR     = .
+
+THIRD_PARTY_MODDIRS = $(dir $(wildcard $(TOPDIR)/third_party/*/setup.py))
+THIRD_PARTY_MODULES = $(notdir $(patsubst %/,%,$(THIRD_PARTY_MODDIRS)))
+
+# Put it first so that "make" without argument is like "make help".
+#-------------------------------------------
+help: $(SPHINXBUILD)
+	@$(SPHINXRUN) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help
+
+# Set up a virtualenv
+#-------------------------------------------
+$(VENV_ROOT):
+	mkdir -p $<
+
+PYTHONPATH = $(TOPDIR)
+export PYTHONPATH
+
+$(VENV_ROOT)/bin/activate:
+	virtualenv -p python3 $(VENV_ROOT)
+
+ACTIVATE = source $(VENV_ROOT)/bin/activate
+
+
+# Install the requirements into the virtualenv
+#-------------------------------------------
+
+$(VENV_ROOT)/requirements.stamp: requirements.txt $(VENV_ROOT)/bin/activate | $(VENV_ROOT)
+	$(ACTIVATE); pip install -r requirements.txt
+	@touch $(VENV_ROOT)/requirements.stamp
+
+$(VENV_ROOT)/third_party.stamp: $(VENV_ROOT)/bin/activate | $(VENV_ROOT)
+	$(ACTIVATE); for MODDIR in $(THIRD_PARTY_MODDIRS); do \
+			pip install $$MODDIR; \
+		done
+	@touch $(VENV_ROOT)/third_party.stamp
+
+$(SPHINXBUILD): $(VENV_ROOT)/requirements.stamp $(VENV_ROOT)/third_party.stamp
+	@touch $<
+
+distclean:
+	rm -rf _build $(VENV_ROOT) .Makefile.d
+	mkdir -p _build
+	mkdir -p $(VENV_ROOT)
+
+clean:
+	rm -rf _doxygen verilog
+	@$(ACTIVATE); $(SPHINXRUN) -M clean "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+testenv:
+	@$(ACTIVATE); $(VENV_ROOT)/bin/python3 -c "import sys; print(sys.path)"
+	@# Test the import of third_party python libraries
+	@$(ACTIVATE); for MODULE in $(THIRD_PARTY_MODULES); do \
+			python -c "import $$MODULE; print($$MODULE)"; \
+		done
+	@# Test the import of top level gateware module
+	@$(ACTIVATE); $(VENV_ROOT)/bin/python3 -c "import gateware; print(gateware)"
+
+SPHINXRUN = $(ACTIVATE); $(VENV_ROOT)/bin/python3 $(VENV_ROOT)/bin/sphinx-build
+
+.PHONY: distclean clean
+
+# Generate targets for all the other sphinx commands.
+#-------------------------------------------
+SPHINXCMD = $(SPHINXRUN) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+SPHINXSUBCMD = $(SPHINXRUN) -M $$@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.Makefile.d: $(SPHINXBUILD) Makefile
+	mkdir -p _doxygen
+	$(SPHINXRUN) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) \
+		| grep "^ " \
+		| sed -e's/^ \+//' -e's|^\([^ ]*\) \+.*$$|\1: $(SPHINXBUILD)\n\t$(SPHINXSUBCMD)\n\n.PHONY: \1\n\n|' \
+		> .Makefile.d
+
+-include .Makefile.d
+
+# Get the intersphinx inventory files.
+#-------------------------------------------
+inv:
+	@mkdir -p _build/intersphinx/
+	@./inv.py
+
+.PHONY: inv
+
+# Wiki Documentation
+#--------------------------------------------
+wiki:
+	if [ ! -d wiki ]; then \
+		git clone https://github.com/timvideos/litex-buildenv.wiki.git wiki; \
+	else \
+		cd wiki; git pull; \
+	fi
+
+.PHONY: wiki
+
+# Use sphinx-apidoc to auto-extract docstring
+#--------------------------------------------
+SPHINX_APIDOC = --follow-links --separate --module-first --append-syspath
+apidoc:
+	rm -rf apidoc
+	# Top level like "gateware" and similar
+	$(ACTIVATE); sphinx-apidoc $(SPHINX_APIDOC) -e -o apidoc/litex-buildenv ../ ../third_party ../doc ../build
+	@$(ACTIVATE); for MODULE in $(THIRD_PARTY_MODULES); do \
+			sphinx-apidoc $(SPHINX_APIDOC) -o apidoc/third_party/$$MODULE ../third_party/$$MODULE/$$MODULE; \
+		done
+
+.PHONY: apidoc