From ae21db677451bcad676548ec503331cbac010842 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jon=20Haitz=20Legarreta=20Gorro=C3=B1o?= Date: Sun, 22 Oct 2023 14:32:18 -0400 Subject: [PATCH] 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`. Chang the makefile `SOURCEDIR` variable accordingly. Change the bibliography references paths accordingly in the `README` file. --- .readthedocs.yaml | 4 ++-- README.md | 8 ++++---- {doc => docs}/Makefile | 2 +- {doc => docs}/bibtex/Dumais23_-_Neuroimage_-_FIESTA.bib | 0 {doc => docs}/bibtex/Legarreta21_-_MIA_-_FINTA.bib | 0 .../bibtex/Legarreta22_-_MICCAI-CDMRI_-_CINTA.bib | 0 {doc => docs}/bibtex/Legarreta23_-_MIA_-_GESTA.bib | 0 {doc => docs}/devel/coding_style_guideline.rst | 0 {doc => docs}/make.bat | 0 {doc => docs/source}/conf.py | 7 ++++--- {doc => docs/source}/index.rst | 0 11 files changed, 11 insertions(+), 10 deletions(-) rename {doc => docs}/Makefile (96%) rename {doc => docs}/bibtex/Dumais23_-_Neuroimage_-_FIESTA.bib (100%) rename {doc => docs}/bibtex/Legarreta21_-_MIA_-_FINTA.bib (100%) rename {doc => docs}/bibtex/Legarreta22_-_MICCAI-CDMRI_-_CINTA.bib (100%) rename {doc => docs}/bibtex/Legarreta23_-_MIA_-_GESTA.bib (100%) rename {doc => docs}/devel/coding_style_guideline.rst (100%) rename {doc => docs}/make.bat (100%) rename {doc => docs/source}/conf.py (92%) rename {doc => docs/source}/index.rst (100%) diff --git a/.readthedocs.yaml b/.readthedocs.yaml index e8b53c5..04c81aa 100644 --- a/.readthedocs.yaml +++ b/.readthedocs.yaml @@ -15,11 +15,11 @@ build: - liblapack-dev jobs: pre_build: - - sphinx-apidoc -f -o doc . + - sphinx-apidoc -f -o docs . # 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/README.md b/README.md index ec932dd..95a0df9 100644 --- a/README.md +++ b/README.md @@ -115,7 +115,7 @@ This software is distributed under a particular license. Please see the [*LICENSE*](LICENSE) file for details. -[FINTA]: ./doc/bibtex/Legarreta21_-_MIA_-_FINTA.bib "Filtering in tractography using autoencoders (FINTA)" -[CINTA]: ./doc/bibtex/Legarreta22_-_MICCAI-CDMRI_-_CINTA.bib "Clustering in Tractography Using Autoencoders (CINTA)" -[GESTA]: ./doc/bibtex/Legarreta23_-_MIA_-_GESTA.bib "Generative Sampling in Bundle Tractography using Autoencoders (GESTA)" -[FIESTA]: ./doc/bibtex/Dumais23_-_Neuroimage_-_FIESTA.bib "FIESTA: Autoencoders for accurate fiber segmentation in tractography" +[FINTA]: ./docs/bibtex/Legarreta21_-_MIA_-_FINTA.bib "Filtering in tractography using autoencoders (FINTA)" +[CINTA]: ./docs/bibtex/Legarreta22_-_MICCAI-CDMRI_-_CINTA.bib "Clustering in Tractography Using Autoencoders (CINTA)" +[GESTA]: ./docs/bibtex/Legarreta23_-_MIA_-_GESTA.bib "Generative Sampling in Bundle Tractography using Autoencoders (GESTA)" +[FIESTA]: ./docs/bibtex/Dumais23_-_Neuroimage_-_FIESTA.bib "FIESTA: Autoencoders for accurate fiber segmentation in tractography" diff --git a/doc/Makefile b/docs/Makefile similarity index 96% rename from doc/Makefile rename to docs/Makefile index 26217e7..d0c3cbf 100644 --- a/doc/Makefile +++ b/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/bibtex/Dumais23_-_Neuroimage_-_FIESTA.bib b/docs/bibtex/Dumais23_-_Neuroimage_-_FIESTA.bib similarity index 100% rename from doc/bibtex/Dumais23_-_Neuroimage_-_FIESTA.bib rename to docs/bibtex/Dumais23_-_Neuroimage_-_FIESTA.bib diff --git a/doc/bibtex/Legarreta21_-_MIA_-_FINTA.bib b/docs/bibtex/Legarreta21_-_MIA_-_FINTA.bib similarity index 100% rename from doc/bibtex/Legarreta21_-_MIA_-_FINTA.bib rename to docs/bibtex/Legarreta21_-_MIA_-_FINTA.bib diff --git a/doc/bibtex/Legarreta22_-_MICCAI-CDMRI_-_CINTA.bib b/docs/bibtex/Legarreta22_-_MICCAI-CDMRI_-_CINTA.bib similarity index 100% rename from doc/bibtex/Legarreta22_-_MICCAI-CDMRI_-_CINTA.bib rename to docs/bibtex/Legarreta22_-_MICCAI-CDMRI_-_CINTA.bib diff --git a/doc/bibtex/Legarreta23_-_MIA_-_GESTA.bib b/docs/bibtex/Legarreta23_-_MIA_-_GESTA.bib similarity index 100% rename from doc/bibtex/Legarreta23_-_MIA_-_GESTA.bib rename to docs/bibtex/Legarreta23_-_MIA_-_GESTA.bib diff --git a/doc/devel/coding_style_guideline.rst b/docs/devel/coding_style_guideline.rst similarity index 100% rename from doc/devel/coding_style_guideline.rst rename to docs/devel/coding_style_guideline.rst diff --git a/doc/make.bat b/docs/make.bat similarity index 100% rename from doc/make.bat rename to docs/make.bat diff --git a/doc/conf.py b/docs/source/conf.py similarity index 92% rename from doc/conf.py rename to docs/source/conf.py index 7accc6d..af3f91a 100644 --- a/doc/conf.py +++ b/docs/source/conf.py @@ -11,16 +11,17 @@ # documentation root, use os.path.abspath to make it absolute, like shown here. # import os +import sys from datetime import datetime from importlib.metadata import version as vers -# import sys import tomli -# sys.path.insert(0, os.path.abspath('.')) +# Location of files where Sphinx will look for docstrings +sys.path.insert(0, os.path.abspath("..")) # Load the release info into a dict by explicit execution -with open(os.path.join("..", "pyproject.toml"), "rb") as f: +with open(os.path.join("../..", "pyproject.toml"), "rb") as f: info = tomli.load(f) # -- Project information ----------------------------------------------------- diff --git a/doc/index.rst b/docs/source/index.rst similarity index 100% rename from doc/index.rst rename to docs/source/index.rst