Reorganization of the documentation folder

.circleci/config.yml

@@ -50,15 +50,15 @@ jobs:
           no_output_timeout: 40m
       # store the documentation for see it in a PR
       - store_artifacts:
-          path: doc_conf/_build/html
+          path: docs/_build/html
           destination: documentation
       - store_artifacts:
           path: ~/output_sphinx.log
           destination: log.txt
       # Persists generated documentation so that it can be attached and deployed
       # in the 'deploy-documentation' step.
       - persist_to_workspace:
-          root: doc_conf/_build/html
+          root: docs/_build/html
           paths: .
       - save_cache:
           # cache some library
@@ -80,15 +80,15 @@ jobs:
               set -x -e
               wget $GITHUB_ARTIFACT_URL
               unzip pytest-results-all.zip -d test_reports
-              mkdir -p doc_conf/_build/html
-              mv test_reports doc_conf/_build/html
+              mkdir -p docs/_build/html
+              mv test_reports docs/_build/html
       # store the reports to display for a PR
       - store_artifacts:
-          path: doc_conf/_build/html/test_reports
-          destination: doc_conf/test_reports
+          path: docs/_build/html/test_reports
+          destination: docs/test_reports
       # store the reports for adding them to the documentation
       - persist_to_workspace:
-          root: doc_conf/_build/html/
+          root: docs/_build/html/
           paths: .
 
   deploy-documentation:
@@ -108,19 +108,19 @@ jobs:
       # Attach documentation generated in the 'build-documentation' step so that it can be
       # deployed.
       - attach_workspace:
-          at: doc_conf/_build/html
+          at: docs/_build/html
       - run:
           name: 
             "Add the ssh key and list the file in the documentation"
           command: |
               mkdir -p ~/.ssh
               ssh-keyscan github.com >> ~/.ssh/known_hosts
-              ls -ltrh doc_conf/_build/html
+              ls -ltrh docs/_build/html
       - run:
           name: "Deploy documentation"
           command: |
             if [[ "${CIRCLE_BRANCH}" =~ ^main$|^[0-9]+\.[0-9]+\.X$ ]]; then
-              bash ./tools/documentation/circleci/push_doc.sh doc_conf/_build/html
+              bash ./tools/documentation/circleci/push_doc.sh docs/_build/html
             fi
 
   # this action is only to avoid any error

.github/workflows/circleci-artifact.yml

@@ -34,7 +34,7 @@ jobs:
         with:
           repo-token: ${{ secrets.GITHUB_TOKEN }}
           api-token: ${{ secrets.CIRCLE_CI }}
-          artifact-path: 0/doc_conf/test_reports/index.html
+          artifact-path: 0/docs/test_reports/index.html
           circleci-jobs: get-tests-reports
           job-title: Check the reports of the tests here!
 

.gitignore

@@ -11,10 +11,10 @@ __pycache__
 *.egg-info
 .coverage*
 
-# documenation 
-doc
-doc_conf/auto_examples/
-doc_conf/generated/
+# documentation 
+docs/_build/
+docs/src/generated/
+docs/src/ssg_execution_times.rst
 
 # file generated by hatch
 src/hidimstat/_version.py

doc_conf/Makefile → docs/Makefile

@@ -2,18 +2,21 @@
 #
 
 # You can set these variables from the command line.
-SPHINXOPTS    = -j auto -W --keep-going -n
+SPHINXOPTS    = -j auto -W --keep-going -n 
 # -j/--jobs:		    N processes in parallel (auto=number of CPUs)
 # -W/--fail-on-warning: Turn warnings into errors.
 # --keep-going:         Runs sphinx-build to completion and exits  
 #			    		with exit status 1 if errors are encountered.
 # -n/--nitpicky:	    This generates warnings for all missing references.
 SPHINXBUILD   = sphinx-build
 PAPER         =
-BUILDDIR      = _build
+BUILDDIR      = ./_build
 
 GITHUB_PAGES_BRANCH = gh-pages
-OUTPUTDIR = _build/html
+SOURCEDIR = ./src
+OUTPUTDIR = ./_build/html
+
+# move to source dir before any operation
 
 # add an option for selecting the example to run
 ifneq ($(EXAMPLES_PATTERN),)
@@ -28,7 +31,7 @@ endif
 # Internal variables.
 PAPEROPT_a4     = -D latex_paper_size=a4
 PAPEROPT_letter = -D latex_paper_size=letter
-ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) $(EXAMPLES_PATTERN_OPTS) .
+ALLSPHINXOPTS   = -c tools -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) $(EXAMPLES_PATTERN_OPTS)
 # the i18n builder cannot share the environment and doctrees with the others
 I18NSPHINXOPTS  = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
 
@@ -55,50 +58,49 @@ help:
 .PHONY: clean
 
 clean:
-	rm -rf $(BUILDDIR)/*
-	rm -rf auto_examples/
-	rm -rf generated/*
-	rm -rf modules/*
+	rm -rfv $(BUILDDIR)/*
+	rm -rfv $(SOURCEDIR)/generated/*
+	rm -rfv $(SOURCEDIR)/sg_execution_times.rst
 
 html-noplot:
-	$(SPHINXBUILD) -D plot_gallery=0 -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
+	$(SPHINXBUILD) -D plot_gallery=0 -b html $(ALLSPHINXOPTS) $(SOURCEDIR) $(BUILDDIR)/html
 	@echo
 	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
 
 .PHONY: html
 html:
-	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
+	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(SOURCEDIR) $(BUILDDIR)/html
 	@echo
 	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
 
 .PHONY: dirhtml
 dirhtml:
-	$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
+	$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(SOURCEDIR) $(BUILDDIR)/dirhtml
 	@echo
 	@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
 
 .PHONY: singlehtml
 singlehtml:
-	$(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml
+	$(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(SOURCEDIR) $(BUILDDIR)/singlehtml
 	@echo
 	@echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."
 
 .PHONY: pickle
 pickle:
-	$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
+	$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(SOURCEDIR) $(BUILDDIR)/pickle
 	@echo
 	@echo "Build finished; now you can process the pickle files."
 
 .PHONY: htmlhelp
 htmlhelp:
-	$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
+	$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(SOURCEDIR) $(BUILDDIR)/htmlhelp
 	@echo
 	@echo "Build finished; now you can run HTML Help Workshop with the" \
 		  ".hhp project file in $(BUILDDIR)/htmlhelp."
 
 .PHONY: qthelp
 qthelp:
-	$(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
+	$(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(SOURCEDIR) $(BUILDDIR)/qthelp
 	@echo
 	@echo "Build finished; now you can run "qcollectiongenerator" with the" \
 		  ".qhcp project file in $(BUILDDIR)/qthelp, like this:"
@@ -108,41 +110,41 @@ qthelp:
 
 .PHONY: latex
 latex:
-	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(SOURCEDIR) $(BUILDDIR)/latex
 	@echo
 	@echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
 	@echo "Run \`make' in that directory to run these through (pdf)latex" \
 		  "(use \`make latexpdf' here to do that automatically)."
 
 .PHONY: latexpdf
 latexpdf:
-	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(SOURCEDIR) $(BUILDDIR)/latex
 	@echo "Running LaTeX files through pdflatex..."
 	$(MAKE) -C $(BUILDDIR)/latex all-pdf
 	@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
 
 .PHONY: changes
 changes:
-	$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
+	$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(SOURCEDIR) $(BUILDDIR)/changes
 	@echo
 	@echo "The overview file is in $(BUILDDIR)/changes."
 
 .PHONY: linkcheck
 linkcheck:
-	$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
+	$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(SOURCEDIR) $(BUILDDIR)/linkcheck
 	@echo
 	@echo "Link check complete; look for any errors in the above output " \
 		  "or in $(BUILDDIR)/linkcheck/output.txt."
 
 .PHONY: doctest
 doctest:
-	$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
+	$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(SOURCEDIR) $(BUILDDIR)/doctest
 	@echo "Testing of doctests in the sources finished, look at the " \
 		  "results in $(BUILDDIR)/doctest/output.txt."
 
 .PHONY: coverage
 coverage:
-	$(SPHINXBUILD) -b coverage $(ALLSPHINXOPTS) $(BUILDDIR)/coverage
+	$(SPHINXBUILD) -b coverage $(ALLSPHINXOPTS) $(SOURCEDIR) $(BUILDDIR)/coverage
 	@echo "Testing of coverage in the sources finished, look at the " \
 		  "results in $(BUILDDIR)/coverage/python.txt."
 

doc_conf/api.rst → docs/src/api.rst

@@ -13,7 +13,7 @@ Functions
 =========
 
 .. autosummary::
-   :toctree: generated/
+   :toctree: ./generated/api/function/
    :template: function.rst
 
    quantile_aggregation
@@ -33,7 +33,7 @@ Classes
 =======
 
 .. autosummary::
-   :toctree: generated/
+   :toctree: ./generated/api/class/
    :template: class.rst
 
    BasePerturbation

docs/src/dev

@@ -0,0 +1 @@
+../../tools/documentation_developer/

doc_conf/index.rst → docs/src/index.rst

@@ -72,7 +72,7 @@ To build the documentation you will need to run:
 .. code-block::
 
     pip install -U .[doc]
-    cd doc_conf
+    cd docs
     make html
 
 
@@ -173,13 +173,13 @@ For Knockoffs Inference:
 
 References
 ----------
-.. bibliography:: references.bib
+.. bibliography:: ../tools/references.bib
 
 
 .. toctree::
   :hidden:
   :maxdepth: 1
 
   api
-  auto_examples/index
+  generated/gallery/examples/index
   dev/index

doc_conf/conf.py → docs/tools/conf.py

@@ -43,7 +43,7 @@
 ]
 
 # Add any paths that contain templates here, relative to this directory.
-templates_path = ["_templates"]
+templates_path = ["./_templates"]
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
 # This patterns also effect to html_static_path and html_extra_path
@@ -62,8 +62,8 @@
 # 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,
 # so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = ["_static"]
-html_logo = "_static/logo.png"
+html_static_path = ["./_static"]
+html_logo = "./_static/logo.png"
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 html_theme = "pydata_sphinx_theme"
@@ -118,15 +118,15 @@
 # Generate the plots for the gallery
 matplotlib.use("agg")
 sphinx_gallery_conf = {
-    "examples_dirs": ["../examples"],
-    "gallery_dirs": ["auto_examples"],
+    "examples_dirs": ["../../examples"],
+    "gallery_dirs": ["./generated/gallery/examples"],
     "plot_gallery": "True",
     "thumbnail_size": (160, 112),
     "min_reported_time": 1.0,
     "abort_on_example_error": False,
     "image_scrapers": ("matplotlib",),
     "doc_module": "hidimstat",
-    "backreferences_dir": "generated",
+    "backreferences_dir": "./generated/gallery/backreference/",
     "parallel": True,
     "show_memory": False,  # can't show memory if it's in parallel
     "reference_url": {

tools/documentation/circleci/build_doc.sh

@@ -114,7 +114,7 @@ else
 fi
 
 # The pipefail is requested to propagate exit code
-set -o pipefail && cd doc_conf && make $make_args 2>&1 | tee ~/log.txt
+set -o pipefail && cd docs && make $make_args 2>&1 | tee ~/log.txt
 cd -
 
 set +o pipefail
@@ -124,14 +124,14 @@ affected_doc_paths() {
     # generate a list fo the file modified in the PR
     files=$(git diff --name-only origin/main...$CIRCLE_SHA1)
     # list of the modified documentation files
-    echo "$files" | grep ^doc_conf/.*\.rst | sed 's/^doc_conf\/\(.*\)\.rst$/\1.html/'
+    echo "$files" | grep ^docs/src/.*\.rst | sed 's/^docs\/src\/\(.*\)\.rst$/\1.html/'
     # list of the modified examples 
     echo "$files" | grep ^examples/.*.py | sed 's/^\(.*\)\.py$/auto_\1.html/'
     # list of the modifed source file
     project_files=$(echo "$files" | grep 'src/hidimstat/')
     if [ -n "$project_files" ]
     then
-        grep -hlR -f<(echo "$project_files" | sed 's/src\/hidimstat\//hidimstat\./') doc_conf/_build/html/generated | cut -d/ -f4- 
+        grep -hlR -f<(echo "$project_files" | sed 's/src\/hidimstat\//hidimstat\./') docs/_build/html/generated | cut -d/ -f4- 
     fi
 }
 
@@ -145,5 +145,5 @@ then
     echo '<html><body><ul>'
     echo "$affected" | sed 's|.*|<li><a href="&">&</a></li>|'
     echo '</ul><p>General: <a href="index.html">Home</a> | <a href="api.html">API Reference</a> | <a href="auto_examples/index.html">Examples</a></p></body></html>'
-    ) > 'doc_conf/_build/html/_changed.html'
+    ) > 'docs/_build/html/_changed.html'
 fi

tools/documentation_developer/building_documentation.rst

@@ -10,11 +10,11 @@ new sphinx warnings by building the documentation locally and try to fix them.**
 
     pip install .[doc]
 
-To build the documentation, you need to be in the ``doc_conf`` folder:
+To build the documentation, you need to be in the `docs` folder:
 
 .. prompt:: bash
 
-    cd doc_conf
+    cd docs
 
 In the vast majority of cases, you only need to generate the web site without
 the example gallery (equivalent to ``make html-noplot``):