Reorganization of the documentation folder (#304)

* chnage name of folder documentation

* change doc_conf in scrips

* move the documentation file in src

* move other file for the documentation in src

* change path for documentation

* move side file to _utils

* add a init file for python file

* change place of elements for the documentation

* fix path

* fix results

* add missing a file in ignore

* fix make file

* Update docs/src/api.rst

Co-authored-by: bthirion <[email protected]>

* fix path of contributing

* fix path contributing

[skip tests] [doc quick]

* test skip tests

[skip tests]

* fix path for tests reports

* fix path of log of building doc

---------

Co-authored-by: bthirion <[email protected]>

Author: lionelkusch

.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: documentation/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/dev

@@ -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/Makefile renamed to docs/Makefile

@@ -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

doc_conf/api.rst renamed to docs/src/api.rst

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

docs/src/dev

@@ -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,14 +173,13 @@ For Knockoffs Inference:
 
 References
 ----------
-.. bibliography:: references.bib
+.. bibliography:: ../tools/references.bib
 
 
 .. toctree::
   :hidden:
   :maxdepth: 1
 
   api
-  dev/CONTRIBUTING
-  auto_examples/index
+  generated/gallery/examples/index
   dev/index