STYLE: Make documentation module consistent with Sphinx conventions

Make the documentation module consistent with Sphinx conventions: - Rename the module to `docs`. - Host the configuration file and index file in `docs/sources`. Change the makefile `SOURCEDIR` variable accordingly. - Change accordingly the `sphinx-apidoc` command output path argument, and the configuration file location in the `.readthedocs.yaml` config file. - Change the relative paths to the files in the `_static` folder. - Move the Markdown bundle naming and tutorial files and the associated screenshots to the `docs/sources` folder so that all files can be recursively included from the source directory.
SlicerDMRI · Dec 1, 2023 · 09682e7 · 09682e7
1 parent baa171e
commit 09682e7
Show file tree

Hide file tree

Showing 24 changed files with 7 additions and 7 deletions.
diff --git a/.readthedocs.yaml b/.readthedocs.yaml
@@ -16,11 +16,11 @@ build:
   jobs:
     pre_build:
       - pip install --upgrade myst-parser furo
-      - sphinx-apidoc -f -o doc .
+      - sphinx-apidoc -f -o docs/source .
 
 # Build documentation in the doc/ directory with Sphinx
 sphinx:
-  configuration: doc/conf.py
+  configuration: docs/source/conf.py
 
 # We recommend specifying your dependencies to enable reproducible builds:
 # https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html

diff --git a/doc/Makefile → docs/Makefile b/doc/Makefile → docs/Makefile
@@ -5,7 +5,7 @@
 # from the environment for the first two.
 SPHINXOPTS    ?=
 SPHINXBUILD   ?= sphinx-build
-SOURCEDIR     = doc
+SOURCEDIR     = source
 BUILDDIR      = build
 
 # Put it first so that "make" without argument is like "make help".

diff --git a/doc/_static/icon/favicon.ico → docs/_static/icon/favicon.ico b/doc/_static/icon/favicon.ico → docs/_static/icon/favicon.ico
diff --git a/doc/_static/wma_small.jpg → docs/_static/wma_small.jpg b/doc/_static/wma_small.jpg → docs/_static/wma_small.jpg
diff --git a/doc/_static/wma_small_alpha.png → docs/_static/wma_small_alpha.png b/doc/_static/wma_small_alpha.png → docs/_static/wma_small_alpha.png
diff --git a/doc/make.bat → docs/make.bat b/doc/make.bat → docs/make.bat
diff --git a/doc/bundles.md → docs/source/bundles.md b/doc/bundles.md → docs/source/bundles.md
diff --git a/doc/conf.py → docs/source/conf.py b/doc/conf.py → docs/source/conf.py
@@ -27,7 +27,7 @@
 # Load the release info into a dict by explicit execution
 info = {}
 with open(os.path.abspath(os.path.join(
-        os.path.dirname(__file__), "..", "setup.py")), "r") as f:
+        os.path.dirname(__file__), "../..", "setup.py")), "r") as f:
     for line in f:
         if line.startswith(name_setup_str):
             project = (
@@ -93,8 +93,8 @@
 #
 html_theme = "furo"
 
-html_favicon = "_static/icon/favicon.ico"
-html_logo = "_static/wma_small_alpha.png"
+html_favicon = "../_static/icon/favicon.ico"
+html_logo = "../_static/wma_small_alpha.png"
 
 # 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,

diff --git a/doc/index.rst → docs/source/index.rst b/doc/index.rst → docs/source/index.rst
diff --git a/...ect-specific-tractography-parcellation.md → ...ect-specific-tractography-parcellation.md b/...ect-specific-tractography-parcellation.md → ...ect-specific-tractography-parcellation.md
diff --git a/doc/tutorial-pics/fig_csv_clusters.png → ...source/tutorial-pics/fig_csv_clusters.png b/doc/tutorial-pics/fig_csv_clusters.png → ...source/tutorial-pics/fig_csv_clusters.png
diff --git a/doc/tutorial-pics/fig_csv_tracts.png → docs/source/tutorial-pics/fig_csv_tracts.png b/doc/tutorial-pics/fig_csv_tracts.png → docs/source/tutorial-pics/fig_csv_tracts.png
diff --git a/doc/tutorial-pics/fig_ini_fiber_clusters.jpg → .../tutorial-pics/fig_ini_fiber_clusters.jpg b/doc/tutorial-pics/fig_ini_fiber_clusters.jpg → .../tutorial-pics/fig_ini_fiber_clusters.jpg
diff --git a/doc/tutorial-pics/fig_qc_ana_tracts.png → ...ource/tutorial-pics/fig_qc_ana_tracts.png b/doc/tutorial-pics/fig_qc_ana_tracts.png → ...ource/tutorial-pics/fig_qc_ana_tracts.png
diff --git a/doc/tutorial-pics/fig_qc_ini_clusters.png → ...rce/tutorial-pics/fig_qc_ini_clusters.png b/doc/tutorial-pics/fig_qc_ini_clusters.png → ...rce/tutorial-pics/fig_qc_ini_clusters.png
diff --git a/doc/tutorial-pics/fig_qc_input_overlap.jpg → ...ce/tutorial-pics/fig_qc_input_overlap.jpg b/doc/tutorial-pics/fig_qc_input_overlap.jpg → ...ce/tutorial-pics/fig_qc_input_overlap.jpg
diff --git a/doc/tutorial-pics/fig_qc_input_tract.png → ...urce/tutorial-pics/fig_qc_input_tract.png b/doc/tutorial-pics/fig_qc_input_tract.png → ...urce/tutorial-pics/fig_qc_input_tract.png
diff --git a/doc/tutorial-pics/fig_qc_outlier_removed.png → .../tutorial-pics/fig_qc_outlier_removed.png b/doc/tutorial-pics/fig_qc_outlier_removed.png → .../tutorial-pics/fig_qc_outlier_removed.png
diff --git a/doc/tutorial-pics/fig_qc_reg_overlap.jpg → ...urce/tutorial-pics/fig_qc_reg_overlap.jpg b/doc/tutorial-pics/fig_qc_reg_overlap.jpg → ...urce/tutorial-pics/fig_qc_reg_overlap.jpg
diff --git a/doc/tutorial-pics/fig_separated_clusters.png → .../tutorial-pics/fig_separated_clusters.png b/doc/tutorial-pics/fig_separated_clusters.png → .../tutorial-pics/fig_separated_clusters.png
diff --git a/doc/tutorial-pics/fig_terminal_env.png → ...source/tutorial-pics/fig_terminal_env.png b/doc/tutorial-pics/fig_terminal_env.png → ...source/tutorial-pics/fig_terminal_env.png
diff --git a/doc/tutorial-pics/fig_tract_reg_folder.png → ...ce/tutorial-pics/fig_tract_reg_folder.png b/doc/tutorial-pics/fig_tract_reg_folder.png → ...ce/tutorial-pics/fig_tract_reg_folder.png
diff --git a/doc/tutorial-pics/fig_tutorial_data.png → ...ource/tutorial-pics/fig_tutorial_data.png b/doc/tutorial-pics/fig_tutorial_data.png → ...ource/tutorial-pics/fig_tutorial_data.png
diff --git a/setup.py b/setup.py
@@ -35,7 +35,7 @@
     version='0.3.0',
     author='Fan Zhang and Lauren O\'Donnell',
     author_email='[email protected]',
-    packages=find_packages(exclude=["doc"]),
+    packages=find_packages(exclude=["docs"]),
     license='LICENSE.txt',
     description='Processing of whole-brain streamline tractography.',
     long_description=open('README.md').read(),