diff --git a/doc/dev_start_guide.rst b/doc/dev_start_guide.rst
index 1469731e73..010d0ffb75 100644
--- a/doc/dev_start_guide.rst
+++ b/doc/dev_start_guide.rst
@@ -168,15 +168,9 @@ create a virtual environment in the project directory:
.. code-block:: bash
- conda env create -n pytensor-dev -f environment.yml
+ conda env create -f environment.yml
conda activate pytensor-dev
-Afterward, you can install the development dependencies:
-
-.. code-block:: bash
-
- pip install -r requirements.txt
-
Next, ``pre-commit`` needs to be configured so that the linting and code quality
checks are performed before each commit:
@@ -202,12 +196,12 @@ see the `NumPy development guide `_.
Contributing to the documentation
---------------------------------
-To contribute to the documentation, first follow the instructions in the previous section. Afterward, you can install the documentation dependencies in the virtual environment you created:
-
+The documentation build dependencies have also been included in the virtual environment you created. You can also create a separate virtual environment just for the documentation using the `environment.yml` file located inside the `doc` folder.
.. code-block:: bash
- pip install -r requirements-rtd.txt
+ conda env create -f doc/environment.yml
+ conda activate pytensor-docs
You can now build the documentation from the root of the project with:
@@ -215,7 +209,7 @@ You can now build the documentation from the root of the project with:
.. code-block:: bash
- python doc/scripts/docgen.py
+ python -m sphinx -b html ./doc ./html
Afterward, you can go to `html/index.html` and navigate the changes in a browser. One way to do this is to go to the `html` directory and run:
@@ -226,7 +220,7 @@ Afterward, you can go to `html/index.html` and navigate the changes in a browser
python -m http.server
**Do not commit the `html` directory. The documentation is built automatically.**
-
+For more documentation customizations such as different formats e.g., PDF, refer to the `Sphinx documentation `_.
Other tools that might help
===========================
diff --git a/doc/environment.yml b/doc/environment.yml
index 7616f86399..c86375ccf1 100644
--- a/doc/environment.yml
+++ b/doc/environment.yml
@@ -12,7 +12,7 @@ dependencies:
- sphinx>=5.1.0,<6
- mock
- pillow
+ - pymc-sphinx-theme
- pip
- pip:
- - git+https://github.com/pymc-devs/pymc-sphinx-theme
- -e ..
diff --git a/doc/scripts/docgen.py b/doc/scripts/docgen.py
deleted file mode 100644
index 6189099092..0000000000
--- a/doc/scripts/docgen.py
+++ /dev/null
@@ -1,111 +0,0 @@
-import sys
-import os
-import shutil
-import getopt
-from collections import defaultdict
-
-if __name__ == '__main__':
- # Equivalent of sys.path[0]/../..
- throot = os.path.abspath(
- os.path.join(sys.path[0], os.pardir, os.pardir))
-
- options = defaultdict(bool)
- opts, args = getopt.getopt(
- sys.argv[1:],
- 'o:f:',
- ['rst', 'help', 'nopdf', 'cache', 'check', 'test'])
- options.update({x: y or True for x, y in opts})
- if options['--help']:
- print(f'Usage: {sys.argv[0]} [OPTIONS] [files...]')
- print(' -o : output the html files in the specified dir')
- print(' --cache: use the doctree cache')
- print(' --rst: only compile the doc (requires sphinx)')
- print(' --nopdf: do not produce a PDF file from the doc, only HTML')
- print(' --test: run all the code samples in the documentation')
- print(' --check: treat warnings as errors')
- print(' --help: this help')
- print('If one or more files are specified after the options then only '
- 'those files will be built. Otherwise the whole tree is '
- 'processed. Specifying files will implies --cache.')
- sys.exit(0)
-
- if not(options['--rst'] or options['--test']):
- # Default is now rst
- options['--rst'] = True
-
- def mkdir(path):
- try:
- os.mkdir(path)
- except OSError:
- pass
-
- outdir = options['-o'] or (throot + '/html')
- files = None
- if len(args) != 0:
- files = [os.path.abspath(f) for f in args]
- currentdir = os.getcwd()
- mkdir(outdir)
- os.chdir(outdir)
-
- # Make sure the appropriate 'pytensor' directory is in the PYTHONPATH
- pythonpath = os.environ.get('PYTHONPATH', '')
- pythonpath = os.pathsep.join([throot, pythonpath])
- sys.path[0:0] = [throot] # We must not use os.environ.
-
- # Make sure we don't use other devices to compile documentation
- env_th_flags = os.environ.get('PYTENSOR_FLAGS', '')
- os.environ['PYTENSOR_FLAGS'] = 'device=cpu,force_device=True'
-
- def call_sphinx(builder, workdir):
- import sphinx
- if options['--check']:
- extraopts = ['-W']
- else:
- extraopts = []
- if not options['--cache'] and files is None:
- extraopts.append('-E')
- docpath = os.path.join(throot, 'doc')
- inopt = [docpath, workdir]
- if files is not None:
- inopt.extend(files)
- try:
- import sphinx.cmd.build
- ret = sphinx.cmd.build.build_main(
- ['-b', builder] + extraopts + inopt)
- except ImportError:
- # Sphinx < 1.7 - build_main drops first argument
- ret = sphinx.build_main(
- ['', '-b', builder] + extraopts + inopt)
- if ret != 0:
- sys.exit(ret)
-
- if options['--all'] or options['--rst']:
- mkdir("doc")
- sys.path[0:0] = [os.path.join(throot, 'doc')]
- call_sphinx('html', '.')
-
- if not options['--nopdf']:
- # Generate latex file in a temp directory
- import tempfile
- workdir = tempfile.mkdtemp()
- call_sphinx('latex', workdir)
- # Compile to PDF
- os.chdir(workdir)
- os.system('make')
- try:
- shutil.copy(os.path.join(workdir, 'pytensor.pdf'), outdir)
- os.chdir(outdir)
- shutil.rmtree(workdir)
- except OSError as e:
- print('OSError:', e)
-
- if options['--test']:
- mkdir("doc")
- sys.path[0:0] = [os.path.join(throot, 'doc')]
- call_sphinx('doctest', '.')
-
- # To go back to the original current directory.
- os.chdir(currentdir)
-
- # Reset PYTENSOR_FLAGS
- os.environ['PYTENSOR_FLAGS'] = env_th_flags
diff --git a/environment.yml b/environment.yml
index e84f1c5207..0e5d3387af 100644
--- a/environment.yml
+++ b/environment.yml
@@ -37,6 +37,7 @@ dependencies:
- pygments
- pydot
- ipython
+ - pymc-sphinx-theme
# code style
- ruff
# developer tools