Straightened out documentation build system (#130)

* Removed import of bsb in conf.py, use autodoc_mock instead of our own

* Cleaned up and simplified conf.py

.github/workflows/docs.yml

@@ -17,8 +17,8 @@ jobs:
       run: sudo apt-get install -y openmpi-bin libopenmpi-dev
     - name: Install dependencies
       run: |
-        python -m pip install --upgrade pip
-        pip install -r requirements.txt --no-use-pep517
+        python -m pip install pip
+        pip install -r docs/requirements.txt
         pip install sphinx
     - name: Build documentations
       run: cd docs && sphinx-build -n -b html source build/html

bsb/models.py

@@ -14,6 +14,10 @@
 
 
 class CellType(SortableByAfter):
+    """
+    A CellType represents a population of cells.
+    """
+
     def __init__(self, name, placement=None):
         self.name = name
         self.placement = placement
@@ -108,6 +112,11 @@ def list_all_morphologies(self):
 
 
 class Layer(dimensions, origin):
+    """
+    A Layer represents a compartment of the topology of the simulation volume that slices
+    the volume in horizontally stacked portions.
+    """
+
     def __init__(self, name, origin, dimensions, scaling=True):
         # Name of the layer
         self.name = name

bsb/reporting.py

@@ -68,7 +68,7 @@ def warn(message, category=None):
     Send a warning.
 
     :param message: Warning message
-    :type message: string
+    :type message: str
     :param category: The class of the warning.
     """
     if _verbosity > 0:

docs/requirements.txt

@@ -1,12 +1,4 @@
-h5py==2.10.0
-joblib==0.14.0
-numpy==1.17.3
-scikit-learn==0.21.3
-scipy==1.3.1
-six==1.12.0
-plotly==4.1.0
-pre-commit==1.21.0
-black==20.8b1
+sphinx==3.2.1
 sphinx_rtd_theme==0.4.3
 colour==0.1.5
 errr==0.2.0

docs/source/conf.py

@@ -16,6 +16,7 @@
 import sys, types
 
 sys.path.insert(0, os.path.abspath("../.."))
+
 autodoc_mock_imports = [
     "glia",
     "patch",
@@ -25,36 +26,33 @@
     "arborize",
     "rtree",
     "rtree.index",
+    "h5py",
+    "joblib",
+    "numpy",
+    "sklearn",
+    "scipy",
+    "six",
+    "plotly",
 ]
 
 
-class Mock(types.ModuleType):
-    def __repr__(self):
-        return "<mocked object '{}'>".format(self.__name__)
-
-    def __getattr__(self, attr):
-        return Mock("recursive")
-
-    def __call__(self, *args, **kwargs):
-        return 1
-
-
-for mod in autodoc_mock_imports:
-    sys.modules[mod] = Mock(mod)
-
-import bsb, bsb.config
-
-
 # -- Project information -----------------------------------------------------
 
 project = "DBBS Brain Scaffold Builder"
 copyright = "2020, Neurocomputational Lab, Department of Brain and Behavioral Sciences, University of Pavia"
 author = "Robin De Schepper et al., Neurocomputational Lab, University of Pavia"
 
+bsb_init_file = os.path.join(os.path.dirname(__file__), "..", "..", "bsb", "__init__.py")
+with open(bsb_init_file, "r") as f:
+    for line in f:
+        if "__version__ = " in line:
+            exec(line.strip())
+            break
+
 # The short X.Y version
-version = ".".join(bsb.__version__.split(".")[0:2])
+version = ".".join(__version__.split(".")[0:2])
 # The full version, including alpha/beta/rc tags
-release = bsb.__version__
+release = __version__
 
 
 # -- General configuration ---------------------------------------------------

docs/source/configuration.rst

@@ -117,15 +117,17 @@ The size of the Z dimension of the simulation volume.
   }
 
 .. note::
+
   The Y can not be set directly as it is a result of stacking/placing the layers.
   It's possible to place cells outside of the simulation volume, and even to place
   layers outside of the volume, but it is not recommended behavior. The X and Z
   size are merely the base/anchor and a good indicator for the scale of the
   simulation, but they aren't absolute restrictions.
 
 .. warning::
-  Do not modify these values directly on the configuration object: It will not
-  rescale your layers. Use :func:`resize <.configuration.ScaffoldConfig.resize>` instead.
+
+  Do not modify these values directly on the configuration object: It will not rescale
+  your layers. Use :func:`resize <bsb.configuration.ScaffoldConfig.resize>` instead.
 
 ================
 Layer attributes