diff --git a/.readthedocs.yml b/.readthedocs.yml new file mode 100644 index 000000000..12674777d --- /dev/null +++ b/.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 diff --git a/.travis.yml b/.travis.yml index 47e302e4c..4a85d2a14 100644 --- a/.travis.yml +++ b/.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,16 +29,17 @@ 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" @@ -44,6 +47,10 @@ env: # cores. - JOBS=2 matrix: + #-------------------------------------------- + # Non-firmware building targets + #-------------------------------------------- + - SCRIPT=docs #-------------------------------------------- # Base targets #-------------------------------------------- diff --git a/.travis/docs.sh b/.travis/docs.sh new file mode 100755 index 000000000..c4d770026 --- /dev/null +++ b/.travis/docs.sh @@ -0,0 +1,7 @@ +#! /bin/bash + +set -x +set -e + +cd doc +make html diff --git a/.travis/setup.sh b/.travis/setup-build.sh similarity index 100% rename from .travis/setup.sh rename to .travis/setup-build.sh diff --git a/.travis/setup-docs.sh b/.travis/setup-docs.sh new file mode 100755 index 000000000..33a023876 --- /dev/null +++ b/.travis/setup-docs.sh @@ -0,0 +1,9 @@ +#! /bin/bash + +set -x +set -e + +cd doc +make testenv +make wiki +make apidoc diff --git a/doc/.gitignore b/doc/.gitignore new file mode 100644 index 000000000..4644aaf39 --- /dev/null +++ b/doc/.gitignore @@ -0,0 +1,8 @@ +.Makefile.d +_build +_doxygen +_venv +tools +*-api +apidoc +wiki diff --git a/doc/Makefile b/doc/Makefile new file mode 100644 index 000000000..2e026a32d --- /dev/null +++ b/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 diff --git a/doc/conf.py b/doc/conf.py new file mode 100644 index 000000000..3a7686d2f --- /dev/null +++ b/doc/conf.py @@ -0,0 +1,404 @@ +# -*- coding: utf-8 -*- +# +# LiteX Build Environment documentation build configuration file, created by +# sphinx-quickstart on Wed Feb 21 16:50:36 2018. +# +# This file is execfile()d with the current directory set to its +# containing dir. +# +# Note that not all possible configuration values are present in this +# autogenerated file. +# +# All configuration values have a default; values that are commented out +# serve to show the default. + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. +# +import os +import sys +sys.path.insert(0, os.path.abspath('.')) + +import harden_xml + +on_rtd = os.environ.get('READTHEDOCS', None) == 'True' +if on_rtd: + import subprocess + subprocess.check_call("git submodule update --init -r", shell=True) + subprocess.check_call("git submodule status", shell=True) + subprocess.check_call("make autodoc", shell=True) + +import re +import sphinx_rtd_theme + + +autosummary_generate = True + +# -- General configuration ------------------------------------------------ + +# If your documentation needs a minimal Sphinx version, state it here. +# +# needs_sphinx = '1.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.autodoc', + 'sphinx.ext.autosummary', + 'sphinx.ext.coverage', + 'sphinx.ext.doctest', # Import doctest as examples + 'sphinx.ext.extlinks', # Enable short links + 'sphinx.ext.githubpages', + 'sphinx.ext.ifconfig', + 'sphinx.ext.imgconverter', + 'sphinx.ext.inheritance_diagram', + 'sphinx.ext.intersphinx', # Links to other Sphinx instances + 'sphinx.ext.linkcode', + 'sphinx.ext.mathjax', + 'sphinx.ext.napoleon', # Google and NumPy style docstrings + 'sphinx.ext.todo', + 'sphinx.ext.viewcode', + 'breathe', + 'exhale', + # Sphinx Contrib Packages + #'sphinxcontrib.ansi', # .. ansi-block:: + #'sphinxcontrib.argdoc', # Automatic docs from argparse (maybe 'sphinxcontrib.autoprogram' instead?) + #'sphinxcontrib.cheader', # .. c:header:: - No module named 'sphinx.util.compat' + #'sphinxcontrib.cheeseshop', # :pypi:`Sphinx` + #'sphinxcontrib.cmakedomain', + 'sphinxcontrib.documentedlist', # .. documentedlist:: + 'sphinxcontrib.examplecode', + 'sphinxcontrib.makedomain', # https://bitbucket.org/klorenz/sphinxcontrib-makedomain + 'sphinxcontrib.manpage', # :linuxman:ls(1) + 'sphinxcontrib.spelling', # Spell checking! + #'sphinxcontrib_trio', # Better abstract and similar detection + 'sphinx_git', # .. git_changelog:: + 'sphinx_autodoc_typehints', # + # FPGA Specific + #'sphinxcontrib.gtkwave', # .. gtkwave:: docs/gtkwave_output.vcd + 'sphinxcontrib.wavedrom', # Support wavedrom rendering + 'symbolator_sphinx', # Support symbolator rendering of Verilog +] + +extlinks = { + 'issue': ('https://github.com/timvideos/litex-buildenv/issues/%s', 'issue ')} + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['_templates'] + +# The suffix(es) of source filenames. +# You can specify multiple suffix as a list of string: +# +source_suffix = ['.rst', '.md'] +source_parsers = { + '.md': 'recommonmark.parser.CommonMarkParser', +} + +# The master toctree document. +master_doc = 'index' + +# General information about the project. +project = u'LiteX Build Environment' +copyright = u'2018, TimVideos Group' +author = u'TimVideos Group' + +# The version info for the project you're documenting, acts as replacement for +# |version| and |release|, also used in various other places throughout the +# built documents. +# +# The short X.Y version. +version = u'' +# The full version, including alpha/beta/rc tags. +release = u'' + +# The language for content autogenerated by Sphinx. Refer to documentation +# for a list of supported languages. +# +# This is also used if you do content translation via gettext catalogs. +# Usually you set "language" from the command line for these cases. +language = None + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +# This patterns also effect to html_static_path and html_extra_path +exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store'] + +# The name of the Pygments (syntax highlighting) style to use. +pygments_style = 'sphinx' + +# If true, `todo` and `todoList` produce output, else they produce nothing. +todo_include_todos = True + + +# -- Options for HTML output ---------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +# +html_theme = 'sphinx_rtd_theme' + +# Theme options are theme-specific and customize the look and feel of a theme +# further. For a list of options available for each theme, see the +# documentation. +# +# html_theme_options = {} + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +html_static_path = ['_static'] + +# Enable github links when not on readthedocs +if not on_rtd: + html_context = { + "display_github": True, # Integrate GitHub + "github_user": "timvideos", + "github_repo": "litex-buildenv", + "github_version": "master", + "conf_py_path": "/docs/", + } +else: + # :github_url: ? + html_theme_options = { + "canonical_url": "https://litex-buildenv.rtfd.io/", + } + + +# -- Options for HTMLHelp output ------------------------------------------ + +# Output file base name for HTML help builder. +htmlhelp_basename = 'LiteXBuildEnvironmentdoc' + + +# -- Options for LaTeX output --------------------------------------------- + +latex_elements = { + # The paper size ('letterpaper' or 'a4paper'). + # + # 'papersize': 'letterpaper', + + # The font size ('10pt', '11pt' or '12pt'). + # + # 'pointsize': '10pt', + + # Additional stuff for the LaTeX preamble. + # + # 'preamble': '', + + # Latex figure (float) alignment + # + # 'figure_align': 'htbp', +} + +# Grouping the document tree into LaTeX files. List of tuples +# (source start file, target name, title, +# author, documentclass [howto, manual, or own class]). +latex_documents = [ + (master_doc, 'LiteXBuildEnvironment.tex', u'LiteX Build Environment Documentation', + u'TimVideos Group', 'manual'), +] + + +# -- 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, 'litexbuildenvironment', u'LiteX Build Environment Documentation', + [author], 1) +] + + +# -- 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, 'LiteXBuildEnv', u'Lite X Build Environment Documentation', + author, 'LiteXBuildEnv', 'Environment for building Lite X based applications.', + 'Miscellaneous'), +] + +# -- Breathe + Exhale config for C++ API Documentation -------------------- + +import exhale_multiproject_monkeypatch + +breathe_projects = { + "firmware": "_doxygen/firmware/xml", + "gateware": "_doxygen/gateware/xml", + + "edid-decode": "_doxygen/edid-decode/xml", + "libuip": "_doxygen/libuip/xml", + + "litedram": "_doxygen/litedram/xml", + "liteeth": "_doxygen/liteeth/xml", + "litepcie": "_doxygen/litepcie/xml", + "litesata": "_doxygen/litesata/xml", + "litescope": "_doxygen/litescope/xml", + "liteusb": "_doxygen/liteusb/xml", + "litevideo": "_doxygen/litevideo/xml", + "litex": "_doxygen/litex/xml", + "migen": "_doxygen/migen/xml", +} +breathe_default_project = "firmware" + +breathe_projects_source = { + "firmware": "../firmware", + "gateware": "../gateware", + + "edid-decode": "../third_party/edid-decode", + "libuip": "../third_party/libuip", + + "litedram": "../third_party/litedram", + "liteeth": "../third_party/liteeth", + "litepcie": "../third_party/litepcie", + "litesata": "../third_party/litesata", + "litescope": "../third_party/litescope", + "liteusb": "../third_party/liteusb", + "litevideo": "../third_party/litevideo", + "litex": "../third_party/litex", + "migen": "../third_party/migen", +} + +# Setup the exhale extension + +exhale_args = { + 'verboseBuild': True, + + "rootFileTitle": "Unknown", + "containmentFolder": "unknown", + + # These arguments are required + "rootFileName": "root.rst", + "doxygenStripFromPath": "../", + # Suggested optional arguments + "createTreeView": True, + # TIP: if using the sphinx-bootstrap-theme, you need + # "treeViewIsBootstrap": True, + "exhaleExecutesDoxygen": True, + #"exhaleUseDoxyfile": True, + "exhaleDoxygenStdin": """ +EXCLUDE = ../doc ../third_party/litex/litex/soc/software/compiler_rt ../third_party/litex/litex/soc/software/libcompiler_rt */__pycache__ */_build + +OPTIMIZE_OUTPUT_VERILOG = YES +HIDE_PORT = NO +""", +} + +# Monkey patch exhale.environment_ready to allow multiple doxygen runs with +# different configs. +exhale_projects_args = { + "firmware": { + "exhaleDoxygenStdin": "INPUT = ../firmware"+exhale_args["exhaleDoxygenStdin"], + "containmentFolder": "firmware-api", + "rootFileTitle": "Firmware", + }, + "gateware": { + "exhaleDoxygenStdin": "INPUT = ../gateware"+exhale_args["exhaleDoxygenStdin"], + "containmentFolder": "gateware-api", + "rootFileTitle": "Gateware", + }, + # Third Party Project Includes + "edid-decode": { + "exhaleDoxygenStdin": "INPUT = ../third_party/edid-decode"+exhale_args["exhaleDoxygenStdin"], + "containmentFolder": "third_party-edid-decode-api", + "rootFileTitle": "edid-decode", + }, + "libuip": { + "exhaleDoxygenStdin": "INPUT = ../third_party/libuip"+exhale_args["exhaleDoxygenStdin"], + "containmentFolder": "third_party-libuip-api", + "rootFileTitle": "libuip", + }, + "litedram": { + "exhaleDoxygenStdin": "INPUT = ../third_party/litedram"+exhale_args["exhaleDoxygenStdin"], + "containmentFolder": "third_party-litedram-api", + "rootFileTitle": "LiteDRAM", + }, + "liteeth": { + "exhaleDoxygenStdin": "INPUT = ../third_party/liteeth"+exhale_args["exhaleDoxygenStdin"], + "containmentFolder": "third_party-liteeth-api", + "rootFileTitle": "LiteEth", + }, + "litepcie": { + "exhaleDoxygenStdin": "INPUT = ../third_party/litepcie"+exhale_args["exhaleDoxygenStdin"], + "containmentFolder": "third_party-litepcie-api", + "rootFileTitle": "LitePCIe", + }, + "litesata": { + "exhaleDoxygenStdin": "INPUT = ../third_party/litesata"+exhale_args["exhaleDoxygenStdin"], + "containmentFolder": "third_party-litesata-api", + "rootFileTitle": "LiteSATA", + }, + "litescope": { + "exhaleDoxygenStdin": "INPUT = ../third_party/litescope"+exhale_args["exhaleDoxygenStdin"], + "containmentFolder": "third_party-litescope-api", + "rootFileTitle": "LiteScope", + }, + "liteusb": { + "exhaleDoxygenStdin": "INPUT = ../third_party/liteusb"+exhale_args["exhaleDoxygenStdin"], + "containmentFolder": "third_party-liteusb-api", + "rootFileTitle": "LiteUSB", + }, + "litevideo": { + "exhaleDoxygenStdin": "INPUT = ../third_party/litevideo"+exhale_args["exhaleDoxygenStdin"], + "containmentFolder": "third_party-litevideo-api", + "rootFileTitle": "LiteVideo", + }, + "litex": { + "exhaleDoxygenStdin": "INPUT = ../third_party/litex"+exhale_args["exhaleDoxygenStdin"], + "containmentFolder": "third_party-litex-api", + "rootFileTitle": "LiteX", + }, + "migen": { + "exhaleDoxygenStdin": "INPUT = ../third_party/migen"+exhale_args["exhaleDoxygenStdin"], + "containmentFolder": "third_party-migen-api", + "rootFileTitle": "Migen", + }, +} + +# -- Allow relative links in markdown ------------------------------------- + +from recommonmark.transform import AutoStructify +from markdown_links import MarkdownLinks + +github_doc_root = 'https://github.com/timvideos/litex-buildenv' + +def setup(app): + MarkdownLinks.find_links() + app.add_config_value( + 'recommonmark_config', { + 'github_code_repo': github_doc_root, + 'url_resolver': lambda url: github_doc_root + url, + 'auto_toc_tree_section': 'Contents', + }, True) + app.add_transform(AutoStructify) + app.add_transform(MarkdownLinks) + + +# -- Intersphinx config --------------------------------------------------- + +# Example configuration for intersphinx: refer to the Python standard library. +intersphinx_mapping = { + 'python' : ('https://docs.python.org/3/', (None, '_build/intersphinx/python.inv')), + 'migen' : ('https://m-labs.hk/migen/manual/', (None, '_build/intersphinx/migen.inv')), +} + +# -- ??? ------------------------------------------------------------------ + +def linkcode_resolve(domain, info): + # FIXME: Make this work! + return None + if domain != 'py': + return None + if not info['module']: + return None + filename = info['module'].replace('.', '/') + return "http://somesite/sourcerepo/%s.py" % filename + +# -- Add path to find Python code ----------------------------------------- + +import sys +sys.path.append("..") diff --git a/doc/index.rst b/doc/index.rst new file mode 100644 index 000000000..648058d33 --- /dev/null +++ b/doc/index.rst @@ -0,0 +1,91 @@ +.. LiteX Build Environment documentation master file, created by + sphinx-quickstart on Wed Feb 21 16:50:36 2018. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +Welcome to LiteX Build Environment's documentation! +=================================================== + +.. toctree:: + :maxdepth: 2 + :caption: Contents: + + +.. toctree:: + :maxdepth: 2 + :caption: Python Documentation: + :name: pytoc + :glob: + + apidoc/litex-buildenv + + apidoc/third_party/migen/migen.rst + apidoc/third_party/litex/litex.rst + + apidoc/third_party/litedram/litedram.rst + apidoc/third_party/liteeth/liteeth.rst + apidoc/third_party/litepcie/litepcie.rst + apidoc/third_party/litesata/litesata.rst + apidoc/third_party/litescope/litescope.rst + apidoc/third_party/liteusb/liteusb.rst + apidoc/third_party/litevideo/litevideo.rst + +.. toctree:: + :maxdepth: 2 + :caption: Modules: + :name: modtoc + + apidoc/litex-buildenv/modules.rst + apidoc/third_party/migen/modules.rst + apidoc/third_party/litex/modules.rst + apidoc/third_party/liteusb/modules.rst + apidoc/third_party/litedram/modules.rst + apidoc/third_party/litesata/modules.rst + apidoc/third_party/liteeth/modules.rst + apidoc/third_party/litepcie/modules.rst + apidoc/third_party/litevideo/modules.rst + apidoc/third_party/litescope/modules.rst + +.. toctree:: + :maxdepth: 2 + :caption: API Documentation: + :name: apitoc + :glob: + + gateware-api/root.rst + firmware-api/root.rst + + third_party-migen-api/root.rst + third_party-litex-api/root.rst + third_party-litedram-api/root.rst + third_party-liteeth-api/root.rst + third_party-litepcie-api/root.rst + third_party-litesata-api/root.rst + third_party-litescope-api/root.rst + third_party-liteusb-api/root.rst + third_party-litevideo-api/root.rst + + third_party-edid-decode-api/root.rst + third_party-libuip-api/root.rst + +.. toctree:: + :maxdepth: 2 + :caption: Wiki Documentation: + :name: wikitoc + :glob: + + wiki/Home.md + wiki/_Sidebar.md + + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search` + + +--- + +|release| - |today| diff --git a/doc/inv.py b/doc/inv.py new file mode 100755 index 000000000..6bdb22615 --- /dev/null +++ b/doc/inv.py @@ -0,0 +1,17 @@ +#!/usr/bin/env python3 +import sys +inv_filter = None +if len(sys.argv) > 1: + inv_filter = sys.argv[-1] + +import urllib.request + +import conf +for url, data in conf.intersphinx_mapping.values(): + inv_file = data[-1] + if inv_filter and inv_file != inv_filter: + continue + full_url = url + 'objects.inv' + + print('Downloading '+full_url+' -> '+inv_file) + urllib.request.urlretrieve(full_url, inv_file) diff --git a/doc/requirements.txt b/doc/requirements.txt new file mode 100644 index 000000000..05faab072 --- /dev/null +++ b/doc/requirements.txt @@ -0,0 +1,40 @@ +docutils==0.14 +sphinx==1.7.0 +sphinx-autobuild + +# Important core Sphinx extensions +breathe +exhale +recommonmark +sphinx_rtd_theme +sphinxcontrib-napoleon + +-e hg+https://mithro@bitbucket.org/mithro/sphinxcontrib-domaintools@mithro/use-dictitems-instead-of-dictiteritems-f-1519177628123#egg=sphinxcontrib-domaintools + +# Unimportant Sphinx extensions +#sphinxcontrib-ansi +sphinxcontrib-argdoc +sphinxcontrib-autoprogram +sphinxcontrib-cheader +#sphinxcontrib-cheeseshop +#sphinxcontrib-cmakedomain +sphinxcontrib-documentedlist +sphinxcontrib-examplecode +sphinxcontrib-inlinesyntaxhighlight +sphinxcontrib-makedomain +sphinxcontrib-manpage +sphinxcontrib-spelling +# Weirdly named Sphinx extensions +#sphinxcontrib-trio +sphinx-git +sphinx-autodoc-typehints +sphinx-autodoc-napoleon-typehints + +# Sphinx extensions for support HDL stuff. +symbolator +sphinxcontrib-wavedrom +# sphinxcontrib-gtkwave + +-e git+https://github.com/mithro/sphinx-contrib-mithro#egg=harden_xml&subdirectory=harden_xml +-e git+https://github.com/mithro/sphinx-contrib-mithro#egg=sphinx-contrib-exhale-multiproject&subdirectory=sphinx-contrib-exhale-multiproject +-e git+https://github.com/mithro/sphinx-contrib-mithro#egg=sphinx-contrib-markdown-links&subdirectory=sphinx-contrib-markdown-links