Cleaning up lots of things in the documentation

.gitignore

@@ -8,6 +8,9 @@ benchmarks/results/*
 src/ect/embed_graph.py
 src/ect/embed_cw.py
 
+.vscode
+docs_local
+
 # Byte-compiled / optimized / DLL files
 __pycache__/
 *.py[cod]

Makefile

@@ -28,6 +28,12 @@ html:
 	mkdir docs
 	sphinx-build -b html doc_source docs
 
+html-local:
+	# Running sphinx-build to build html files in a local docs folder
+	rm -rf docs_local
+	mkdir docs_local
+	sphinx-build -b html doc_source docs_local 
+
 benchmark:
 	python benchmarks/run_benchmarks.py
 

doc_source/conf.py

@@ -10,8 +10,10 @@
 # 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.
 #
+# Add the src directory to sys.path so Sphinx can find ect.embed_complex
 import os
 import sys
+sys.path.insert(0, os.path.abspath(os.path.join(os.path.dirname(__file__), '..', 'src')))
 sys.path.insert(0, os.path.abspath('.'))
 sys.path.insert(0, os.path.join(os.path.dirname(__file__),'..'))
 sys.path.insert(0, os.path.join(os.path.dirname(__file__),'..', 'ect' ))
@@ -76,7 +78,7 @@
     'canonical_url': '',
     'analytics_id': 'UA-XXXXXXX-1',  #  Provided by Google in your dashboard
     'logo_only': False,
-    'display_version': True,
+    # 'display_version': True,  # Removed because it is unsupported
     'prev_next_buttons_location': 'bottom',
     'style_external_links': True,
     'style_nav_header_background': '#cececf',
@@ -100,4 +102,4 @@
 # 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']
+# html_static_path = ['_static']

doc_source/contributing.rst

@@ -33,11 +33,11 @@ The `ect` package uses the Sphinx documentation system for generating documentat
 - First, include docstrings in the code which will be autogenerated into the documentation. When in doubt, write too much. 
 - Second, write documentation in the `doc_source` directory using the reStructuredText format. This package also supports writing files in markdown, although there are some issues when dealing with autogenerated content so it's a bit of a mix at the moment. Note that when the documentation is generated, everything in the `docs` folder is deleted and overwritten, so do not do your work in there, it will be lost!
 
-Assuming everything is set up correctly (see the installation instructions in the main documentation), you can generate the documentation by running the following command from the top level folder::
+Assuming everything is set up correctly (see the installation instructions in the main documentation), you can generate the documentation on your local machine by running the following command from the top level folder::
 
-    make html
+    make html-local
 
-This will generate the documentation in the ``docs`` directory. You can view the documentation by opening the ``docs/index.html`` file in your browser.
+This will generate the documentation in the ``docs_local`` directory. You can view the documentation by opening the ``docs_local/index.html`` file in your browser. Do not push anything in the ``docs_local`` folder to the repository, it is only for local viewing; the ``docs`` folder is generated automatically when changes in ``doc_source`` are pushed to the ``main`` branch.
 
 An example of a docstring for a function is given below. Note the use of indentation since rst is picky about it::
 
@@ -89,7 +89,7 @@ If you would like to fix an issue and you are a contributor to the project, plea
 
 - Note that in order for the `pip install` command to work, the version number in the `pyproject.toml` file must be updated.
 - You should also make sure to update the version number to match in the ``doc_source/conf.py`` file. This will ensure that the documentation is updated with the correct version number.
-- Be sure to run ``make all`` before committing to ensure that the code is cleaned, the documentation is up to date, and the tests all pass.
+- Be sure to run ``make all`` before committing to ensure that the code is cleaned, the documentation compiles properly, and the tests all pass.
 
 If you are not a contributor, you will need to fork the code and create a pull request from your fork.
 Note that all pull requests need to be approved by Liz Munch before they can be merged. 

doc_source/embed_complex.md

@@ -41,6 +41,6 @@ K.add_cell(["A", "B", "C"], dim=2)
 ```{eval-rst}
 .. automodule:: ect.embed_complex
    :members:
-   :show-inheritance:
    :undoc-members:
+   :no-index:
 ```

doc_source/tutorials.rst

@@ -6,6 +6,5 @@ Tutorials
    :caption: Contents:
 
    notebooks/Tutorial-EmbeddedComplex
-   notebooks/Tutorial-ExactECT
    notebooks/Matisse/example_matisse