Added flag to disable notebook rendering in Sphinx (#1615)

* add flag to disable nbsphinx * update doc * change approach * remove unnecessary metadata * remove future deprecated command
tardis-sn · Jun 15, 2021 · 66b10ad · 66b10ad
1 parent e847a59
commit 66b10ad
Show file tree

Hide file tree

Showing 6 changed files with 14 additions and 21 deletions.
diff --git a/docs/conf.py b/docs/conf.py
@@ -69,7 +69,10 @@
 numpydoc_show_class_members = False
 extensions += ["matplotlib.sphinxext.plot_directive", "sphinxcontrib.bibtex"]
 
-nbsphinx_execute = "auto"
+if os.getenv('DISABLE_NBSPHINX') == "1":
+    nbsphinx_execute = "never"
+else:
+    nbsphinx_execute = "auto"
 
 nbsphinx_execute_arguments = [
     "--InlineBackend.figure_formats={'svg', 'pdf'}",
@@ -79,6 +82,7 @@
 nbsphinx_prolog = """
 This notebook is available at 
 https://github.com/tardis-sn/tardis/tree/master/docs/{{ env.doc2path(env.docname, base=None) }}
+
 ----
 """
 

diff --git a/docs/development/documentation_guidelines.rst b/docs/development/documentation_guidelines.rst
@@ -20,16 +20,17 @@ Besides this, the functions and classes in your code must always contain **docst
 Building documentation locally
 ==============================
 
-To build TARDIS documentation locally, you can use either of the following commands: ::
+To build TARDIS documentation locally, use the following commands:
 
-    python setup.py build_docs
-    
-or ::
+.. code ::
 
     cd docs
     make html
 
-.. note :: If you're working on a fresh local copy of the TARDIS repository, you might need to do ``python setup.py develop`` before executing these commands.
+.. note :: 
+
+    - If you're working on a fresh local copy of the TARDIS repository, you might need to do ``python setup.py develop`` before executing these commands.
+    - Use ``DISABLE_NBSPHINX=1 make html`` to disable notebook rendering (fast mode).
 
 After running this command, you can find the built docs (i.e. HTML webpages) in ``docs/_build``. Open the ``index.html`` in your browser to see how the documentation looks like with your edits. Navigate to page where you made changes or file that you added to check whether it looks as intended or not.
 

diff --git a/docs/development/index.rst b/docs/development/index.rst
@@ -14,9 +14,9 @@ to the Astropy team for designing it.
     issues
     git_workflow
     documentation_guidelines
+    documentation_preview
     running_tests
     code_quality
-    documentation_preview
     developer_faq
 
 TARDIS core team Instructions

diff --git a/docs/io/optional/custom_source.ipynb b/docs/io/optional/custom_source.ipynb
@@ -165,10 +165,6 @@
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
    "version": "3.7.10"
-  },
-  "nbsphinx": {
-   "execute": "always",
-   "timeout": 600
   }
  },
  "nbformat": 4,

diff --git a/docs/io/output/physical_quantities.ipynb b/docs/io/output/physical_quantities.ipynb
@@ -273,11 +273,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.7.8"
-  },
-  "nbsphinx": {
-   "execute": "always",
-   "timeout": -1
+   "version": "3.7.10"
   }
  },
  "nbformat": 4,

diff --git a/docs/quickstart/quickstart.ipynb b/docs/quickstart/quickstart.ipynb
@@ -133,11 +133,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.8.3"
-  },
-  "nbsphinx": {
-   "execute": "always",
-   "timeout": -1
+   "version": "3.7.10"
   }
  },
  "nbformat": 4,