diff --git a/.circleci/config.yml b/.circleci/config.yml index b42e1f546..faad1bcc3 100644 --- a/.circleci/config.yml +++ b/.circleci/config.yml @@ -50,7 +50,7 @@ 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 @@ -58,7 +58,7 @@ jobs: # 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 diff --git a/.github/workflows/circleci-artifact.yml b/.github/workflows/circleci-artifact.yml index 6d0019e47..b269a5602 100644 --- a/.github/workflows/circleci-artifact.yml +++ b/.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! diff --git a/.gitignore b/.gitignore index 425d3aba2..0ac771869 100644 --- a/.gitignore +++ b/.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 diff --git a/doc_conf/dev b/doc_conf/dev deleted file mode 120000 index f42d8a1de..000000000 --- a/doc_conf/dev +++ /dev/null @@ -1 +0,0 @@ -../tools/documentation_developer/ \ No newline at end of file diff --git a/doc_conf/Makefile b/docs/Makefile similarity index 76% rename from doc_conf/Makefile rename to docs/Makefile index a80da8f16..c2a67f338 100644 --- a/doc_conf/Makefile +++ b/docs/Makefile @@ -2,7 +2,7 @@ # # 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 @@ -10,10 +10,13 @@ SPHINXOPTS = -j auto -W --keep-going -n # -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,7 +110,7 @@ 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" \ @@ -116,33 +118,33 @@ latex: .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." diff --git a/doc_conf/api.rst b/docs/src/api.rst similarity index 88% rename from doc_conf/api.rst rename to docs/src/api.rst index 660d6dc4c..97465e1a7 100644 --- a/doc_conf/api.rst +++ b/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 diff --git a/docs/src/dev b/docs/src/dev new file mode 120000 index 000000000..ee89dc7a9 --- /dev/null +++ b/docs/src/dev @@ -0,0 +1 @@ +../../tools/documentation_developer/ \ No newline at end of file diff --git a/doc_conf/index.rst b/docs/src/index.rst similarity index 98% rename from doc_conf/index.rst rename to docs/src/index.rst index ea7a76f7f..b8057b924 100644 --- a/doc_conf/index.rst +++ b/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,7 +173,7 @@ For Knockoffs Inference: References ---------- -.. bibliography:: references.bib +.. bibliography:: ../tools/references.bib .. toctree:: @@ -181,6 +181,5 @@ References :maxdepth: 1 api - dev/CONTRIBUTING - auto_examples/index + generated/gallery/examples/index dev/index diff --git a/doc_conf/_static/logo.png b/docs/tools/_static/logo.png similarity index 100% rename from doc_conf/_static/logo.png rename to docs/tools/_static/logo.png diff --git a/doc_conf/_static/style.css b/docs/tools/_static/style.css similarity index 100% rename from doc_conf/_static/style.css rename to docs/tools/_static/style.css diff --git a/doc_conf/_templates/class.rst b/docs/tools/_templates/class.rst similarity index 100% rename from doc_conf/_templates/class.rst rename to docs/tools/_templates/class.rst diff --git a/doc_conf/_templates/function.rst b/docs/tools/_templates/function.rst similarity index 100% rename from doc_conf/_templates/function.rst rename to docs/tools/_templates/function.rst diff --git a/doc_conf/conf.py b/docs/tools/conf.py similarity index 94% rename from doc_conf/conf.py rename to docs/tools/conf.py index e0a7e2522..46c83a959 100644 --- a/doc_conf/conf.py +++ b/docs/tools/conf.py @@ -27,7 +27,7 @@ # # We avoid duplicating the information, but we do not use symlinks to be # able to build the docs on Windows -shutil.copyfile("../CONTRIBUTING.rst", "./dev/CONTRIBUTING.rst") +shutil.copyfile("../../CONTRIBUTING.rst", "../src/dev/CONTRIBUTING.rst") # -- General configuration --------------------------------------------------- # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration @@ -50,7 +50,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 @@ -69,8 +69,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" @@ -125,15 +125,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": { diff --git a/doc_conf/references.bib b/docs/tools/references.bib similarity index 100% rename from doc_conf/references.bib rename to docs/tools/references.bib diff --git a/doc_conf/utils.py b/docs/tools/utils.py similarity index 100% rename from doc_conf/utils.py rename to docs/tools/utils.py diff --git a/tools/documentation/circleci/build_doc.sh b/tools/documentation/circleci/build_doc.sh index 0d0d23117..3d972fed2 100755 --- a/tools/documentation/circleci/build_doc.sh +++ b/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 ~/output_sphinx.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 '

General: Home | API Reference | Examples

' - ) > 'doc_conf/_build/html/_changed.html' + ) > 'docs/_build/html/_changed.html' fi diff --git a/tools/documentation_developer/building_documentation.rst b/tools/documentation_developer/building_documentation.rst index 417bccd49..6c96ffdba 100644 --- a/tools/documentation_developer/building_documentation.rst +++ b/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``):