diff --git a/.github/workflows/Pipeline.yml b/.github/workflows/Pipeline.yml index d6985a2..36532a7 100644 --- a/.github/workflows/Pipeline.yml +++ b/.github/workflows/Pipeline.yml @@ -35,26 +35,26 @@ jobs: run: | sudo apt update -qq sudo apt install -y make - make env + make -C docs env - name: 📓 Build the documentation run: | - . ./env/conda/bin/activate f4pga-docs - make html + . ./docs/env/conda/bin/activate f4pga-docs + make -C docs html - name: '📤 Upload artifact: Sphinx HTML' uses: actions/upload-artifact@v3 with: name: Documentation-HTML - path: _build/html + path: docs/_build/html - name: 🚀 Publish site to GitHub Pages if: github.event_name != 'pull_request' run: | - cd _build/html + cd docs/_build/html touch .nojekyll git init - cp ../../.git/config ./.git/config + cp ../../../.git/config ./.git/config git add . git config --local user.email "BuildTheDocs@GitHubActions" git config --local user.name "GitHub Actions" diff --git a/Makefile b/Makefile deleted file mode 100644 index 90e7f84..0000000 --- a/Makefile +++ /dev/null @@ -1,63 +0,0 @@ -# make-env setup ------------------------------------------------------------- - -TOP_DIR := $(realpath $(dir $(lastword $(MAKEFILE_LIST)))) - -# A pip `requirements.txt` file. -REQUIREMENTS_FILE := docs/requirements.txt - -# A conda `environment.yml` file. -ENVIRONMENT_FILE := environment.yml - -include third_party/make-env/conda.mk - -# Makefile for Sphinx documentation ------------------------------------------ - -# You can set these variables from the command line. -SPHINXOPTS = -SPHINXBUILD = sphinx-build -PAPER = -BUILDDIR = _build - -# Internal variables. -PAPEROPT_a4 = -D latex_paper_size=a4 -PAPEROPT_letter = -D latex_paper_size=letter -ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) docs - -help: - @echo "Please use \`make ' where is one of" - @echo " html to make standalone HTML files" - @echo " dirhtml to make HTML files named index.html in directories" - @echo " singlehtml to make a single large HTML file" - @echo " pickle to make pickle files" - @echo " json to make JSON files" - @echo " htmlhelp to make HTML files and a HTML help project" - @echo " epub to make an epub" - @echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter" - @echo " latexpdf to make LaTeX files and run them through pdflatex" - @echo " text to make text files" - @echo " man to make manual pages" - @echo " changes to make an overview of all changed/added/deprecated items" - @echo " linkcheck to check all external links for integrity" - @echo " doctest to run all doctests embedded in the documentation (if enabled)" - @echo " env to create a conda environment with the needed packages" - -clean:: - -rm -rf $(BUILDDIR)/ - -latex: - $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex - sed -i 's/PDFLATEX = pdflatex/PDFLATEX = texfot pdflatex/' $(BUILDDIR)/latex/Makefile - @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)." - -latexpdf: - $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex - sed -i 's/PDFLATEX = pdflatex/PDFLATEX = texfot pdflatex/' $(BUILDDIR)/latex/Makefile - @echo "Running LaTeX files through pdflatex..." - make -C $(BUILDDIR)/latex all-pdf - @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." - -%: - $(SPHINXBUILD) -b $@ $(ALLSPHINXOPTS) $(BUILDDIR)/$@ diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 0000000..4bac849 --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,38 @@ + +TOP_DIR := $(realpath $(dir $(lastword $(MAKEFILE_LIST)))) +REQUIREMENTS_FILE := requirements.txt +ENVIRONMENT_FILE := environment.yml + +include ../third_party/make-env/conda.mk + +# NOTE: make env to create a conda environment with the needed packages + +SPHINXOPTS = +SPHINXBUILD = sphinx-build +PAPER = +BUILDDIR = _build + +PAPEROPT_a4 = -D latex_paper_size=a4 +PAPEROPT_letter = -D latex_paper_size=letter +ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . + +clean:: + -rm -rf $(BUILDDIR)/ + +latex: + $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex + sed -i 's/PDFLATEX = pdflatex/PDFLATEX = texfot pdflatex/' $(BUILDDIR)/latex/Makefile + @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)." + +latexpdf: + $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex + sed -i 's/PDFLATEX = pdflatex/PDFLATEX = texfot pdflatex/' $(BUILDDIR)/latex/Makefile + @echo "Running LaTeX files through pdflatex..." + make -C $(BUILDDIR)/latex all-pdf + @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." + +%: + $(SPHINXBUILD) -b $@ $(ALLSPHINXOPTS) $(BUILDDIR)/$@ diff --git a/environment.yml b/docs/environment.yml similarity index 80% rename from environment.yml rename to docs/environment.yml index a82d238..60b8d98 100644 --- a/environment.yml +++ b/docs/environment.yml @@ -8,4 +8,4 @@ dependencies: - pygobject - pip - pip: - - -r docs/requirements.txt + - -r requirements.txt diff --git a/readthedocs.yml b/readthedocs.yml index 0f2632f..dadd759 100644 --- a/readthedocs.yml +++ b/readthedocs.yml @@ -1,23 +1,18 @@ -# .readthedocs.yml # Read the Docs configuration file # See https://docs.readthedocs.io/en/stable/config-file/v2.html for details -# Required version: 2 -# Build documentation in the docs/ directory with Sphinx sphinx: configuration: docs/conf.py -# Optionally build your docs in additional formats such as PDF and ePub formats: [] -# Optionally set the version of Python and requirements required to build your docs python: version: "3.7" conda: - environment: environment.yml + environment: docs/environment.yml submodules: include: all