Preparatory configuration updates (#1313)

* Split development and documentation requirements

* Add sphinx-copybutton and sphinx-design

* IPython

* Cache

* Disable domain indices & copying source

.github/workflows/documentation.yml

@@ -35,7 +35,7 @@ jobs:
         cache: 'pip'
         cache-dependency-path: |
           requirements/base.txt
-          requirements/dev.txt
+          requirements/doc.txt
 
     - name: Install Pandoc
       run: sudo apt-get install --yes pandoc
@@ -44,7 +44,7 @@ jobs:
       run: python -m pip install --upgrade pip
 
     - name: Install HARK
-      run: python -m pip install .[dev]
+      run: python -m pip install .[doc]
 
     - name: Run Sphinx
       run: >

Documentation/conf.py

@@ -20,6 +20,7 @@
 
 # General configuration
 extensions = [
+    # built-in extensions
     "sphinx.ext.autodoc",
     "sphinx.ext.autosummary",
     "sphinx.ext.coverage",
@@ -30,8 +31,11 @@
     "sphinx.ext.mathjax",
     "sphinx.ext.napoleon",
     "sphinx.ext.todo",
+    # third-party extensions
     "nbsphinx",
     "myst_parser",
+    "sphinx_copybutton",
+    "sphinx_design",
 ]
 
 exclude_patterns = [
@@ -93,6 +97,8 @@
 
 html_logo = "images/econ-ark-logo.png"
 html_favicon = "images/econ-ark-logo.png"
+html_domain_indices = False
+html_copy_source = False
 
 # sphinx.ext.intersphinx configuration
 intersphinx_mapping = {

pyproject.toml

@@ -34,7 +34,8 @@ dynamic = ["dependencies", "optional-dependencies"]
 file = "requirements/base.txt"
 
 [tool.setuptools.dynamic.optional-dependencies]
-dev = {"file" = "requirements/dev.txt"}
+dev.file = "requirements/dev.txt"
+doc.file = "requirements/doc.txt"
 
 [project.urls]
 Homepage = "https://github.com/econ-ark/HARK"

requirements/dev.txt

@@ -1,9 +1,5 @@
 estimagic
-nbsphinx>=0.8
 nbval
 pre-commit
 pytest
-pytest-xdist
-myst-parser>=2
-sphinx>=6.1
-pydata-sphinx-theme
+pytest-xdist

requirements/doc.txt

@@ -0,0 +1,11 @@
+sphinx>=6.1
+
+# theme requirements
+pydata-sphinx-theme
+
+# extension requirements
+ipython  # for the Pygments lexer
+myst-parser>=2
+nbsphinx>=0.8
+sphinx-copybutton
+sphinx-design