diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index ed89fc2..7595a41 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -1,46 +1,78 @@ name: CI on: - push: - branches: - - master pull_request: - branches: - - '*' + push: + schedule: + - cron: '0 0/2 * * *' jobs: build: + if: endsWith(github.head_ref || github.ref_name, '.changes') == false runs-on: ubuntu-latest strategy: matrix: - python: ['3.7', '3.8', '3.9'] + python: ['3.7', '3.8', '3.9', '3.10', '3.11'] fail-fast: false + permissions: + contents: write + steps: - - uses: actions/checkout@v2 + - uses: actions/checkout@v3 - - uses: actions/setup-python@v2 + - uses: actions/setup-python@v4 with: python-version: ${{ matrix.python }} + - name: Install tools + run: | + sudo apt -y install libxml2-utils + - name: Install dependencies run: | python -m pip install --upgrade pip pip install -r requirements.txt + pip install -r test/unit/requirements.txt pip install . - - name: Build test/ + - name: Build Test run: | - cd test && make html SPHINXOPTS='-W' + cd test/must-build && make html SPHINXOPTS='-W' - name: Build Test with toc show_parents=hide run: | - cd test && make html SPHINXOPTS='-W -D toc_object_entries_show_parents=hide' + cd test/must-build && make html SPHINXOPTS='-W -D toc_object_entries_show_parents=hide' - name: Build Test with toc show_parents=domain run: | - cd test && make html SPHINXOPTS='-W -D toc_object_entries_show_parents=domain' + cd test/must-build && make html SPHINXOPTS='-W -D toc_object_entries_show_parents=domain' - name: Build Test with toc show_parents=all run: | - cd test && make html SPHINXOPTS='-W -D toc_object_entries_show_parents=all' + cd test/must-build && make html SPHINXOPTS='-W -D toc_object_entries_show_parents=all' + + - name: Run Unit Testing + run: | + cd test/unit + find . -name '*.html' -exec rm {} \; + make html SPHINXOPTS='-W' + (cd _build/html && find . -name '*.html' -exec sh -c 'xmllint {} --xpath '"'"'//div[@role="main"]'"'"' | xmllint --format - > ../../{}' \;) + rm genindex.html index.html search.html php-modindex.html + + - name: Diff Unit Outputs + run: | + cd test/unit + rm -r _build + git add . -N && git diff --exit-code + + - name: Push Unit Changes + if: failure() + uses: stefanzweifel/git-auto-commit-action@v4 + with: + branch: ${{ github.head_ref || github.ref_name }}.changes + push_options: '--force' + commit_message: Unit Changes + commit_user_name: Bot + commit_user_email: bot@example.com + commit_author: Bot diff --git a/.github/workflows/doc.yml b/.github/workflows/doc.yml index a035656..120f7ea 100644 --- a/.github/workflows/doc.yml +++ b/.github/workflows/doc.yml @@ -21,8 +21,8 @@ concurrency: cancel-in-progress: false jobs: - # Build job build: + if: github.repository_owner == 'markstory' runs-on: ubuntu-latest steps: - uses: actions/checkout@v3 @@ -35,7 +35,7 @@ jobs: id: pages uses: actions/configure-pages@v3 - - name: Build doct + - name: Build doc run: make -C doc html - name: Upload artifact @@ -43,7 +43,6 @@ jobs: with: path: doc/_build/html - # Deployment job deploy: environment: name: github-pages diff --git a/.gitignore b/.gitignore index c28a058..508e0cc 100644 --- a/.gitignore +++ b/.gitignore @@ -1,7 +1,8 @@ dist/ build/ doc/_build -test/_build +test/must-build/_build +test/unit/_build *.pyc *.egg-info .DS_Store diff --git a/doc/conf.py b/doc/conf.py index deb030f..39131ca 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -120,7 +120,7 @@ # 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_static_path = ['_static'] # If not '', a 'Last updated on:' timestamp is inserted at every page bottom, # using the given strftime format. diff --git a/test/_static/.gitignore b/test/_static/.gitignore deleted file mode 100644 index e69de29..0000000 diff --git a/test/Makefile b/test/must-build/Makefile similarity index 100% rename from test/Makefile rename to test/must-build/Makefile diff --git a/test/conf.py b/test/must-build/conf.py similarity index 99% rename from test/conf.py rename to test/must-build/conf.py index 6ad727d..e3bde51 100644 --- a/test/conf.py +++ b/test/must-build/conf.py @@ -120,7 +120,7 @@ # 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_static_path = ['_static'] # If not '', a 'Last updated on:' timestamp is inserted at every page bottom, # using the given strftime format. diff --git a/test/index.rst b/test/must-build/index.rst similarity index 100% rename from test/index.rst rename to test/must-build/index.rst diff --git a/test/make.bat b/test/must-build/make.bat similarity index 100% rename from test/make.bat rename to test/must-build/make.bat diff --git a/test/test_doc.rst b/test/must-build/test_doc.rst similarity index 100% rename from test/test_doc.rst rename to test/must-build/test_doc.rst diff --git a/test/test_doc2.rst b/test/must-build/test_doc2.rst similarity index 100% rename from test/test_doc2.rst rename to test/must-build/test_doc2.rst diff --git a/test/test_nesting_regression.rst b/test/must-build/test_nesting_regression.rst similarity index 100% rename from test/test_nesting_regression.rst rename to test/must-build/test_nesting_regression.rst diff --git a/test/unit/Makefile b/test/unit/Makefile new file mode 100644 index 0000000..f61d988 --- /dev/null +++ b/test/unit/Makefile @@ -0,0 +1,130 @@ +# 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) . + +.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest + +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 " qthelp to make HTML files and a qthelp project" + @echo " devhelp to make HTML files and a Devhelp 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)" + +clean: + -rm -rf $(BUILDDIR)/* + +html: + $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html + @echo + @echo "Build finished. The HTML pages are in $(BUILDDIR)/html." + +dirhtml: + $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml + @echo + @echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml." + +singlehtml: + $(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml + @echo + @echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml." + +pickle: + $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle + @echo + @echo "Build finished; now you can process the pickle files." + +json: + $(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json + @echo + @echo "Build finished; now you can process the JSON files." + +htmlhelp: + $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp + @echo + @echo "Build finished; now you can run HTML Help Workshop with the" \ + ".hhp project file in $(BUILDDIR)/htmlhelp." + +qthelp: + $(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp + @echo + @echo "Build finished; now you can run "qcollectiongenerator" with the" \ + ".qhcp project file in $(BUILDDIR)/qthelp, like this:" + @echo "# qcollectiongenerator $(BUILDDIR)/qthelp/sphinxcontrib-rubydomain-acceptancetest.qhcp" + @echo "To view the help file:" + @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/sphinxcontrib-rubydomain-acceptancetest.qhc" + +devhelp: + $(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp + @echo + @echo "Build finished." + @echo "To view the help file:" + @echo "# mkdir -p $$HOME/.local/share/devhelp/sphinxcontrib-rubydomain-acceptancetest" + @echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/sphinxcontrib-rubydomain-acceptancetest" + @echo "# devhelp" + +epub: + $(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub + @echo + @echo "Build finished. The epub file is in $(BUILDDIR)/epub." + +latex: + $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex + @echo + @echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex." + @echo "Run \`make all-pdf' or \`make all-ps' in that directory to" \ + "run these through (pdf)latex." + +latexpdf: latex + $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex + @echo "Running LaTeX files through pdflatex..." + make -C $(BUILDDIR)/latex all-pdf + @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." + +text: + $(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text + @echo + @echo "Build finished. The text files are in $(BUILDDIR)/text." + +man: + $(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man + @echo + @echo "Build finished. The manual pages are in $(BUILDDIR)/man." + +changes: + $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes + @echo + @echo "The overview file is in $(BUILDDIR)/changes." + +linkcheck: + $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck + @echo + @echo "Link check complete; look for any errors in the above output " \ + "or in $(BUILDDIR)/linkcheck/output.txt." + +doctest: + $(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest + @echo "Testing of doctests in the sources finished, look at the " \ + "results in $(BUILDDIR)/doctest/output.txt." diff --git a/test/unit/conf.py b/test/unit/conf.py new file mode 100644 index 0000000..2487b29 --- /dev/null +++ b/test/unit/conf.py @@ -0,0 +1,17 @@ +import sys, os + +sys.path.append(os.path.abspath('..')) + +extensions = [ + 'sphinxcontrib.phpdomain', + 'myst_parser', +] + +myst_enable_extensions = ['colon_fence'] + +source_suffix = '.rst' +master_doc = 'index' + +exclude_patterns = ['_build'] + +html_theme = 'default' diff --git a/test/unit/index.md b/test/unit/index.md new file mode 100644 index 0000000..4cc47cd --- /dev/null +++ b/test/unit/index.md @@ -0,0 +1,7 @@ +# Test: Build all files + +:::{toctree} +:glob: + +** +::: diff --git a/test/unit/make.bat b/test/unit/make.bat new file mode 100644 index 0000000..4310ae1 --- /dev/null +++ b/test/unit/make.bat @@ -0,0 +1,155 @@ +@ECHO OFF + +REM Command file for Sphinx documentation + +if "%SPHINXBUILD%" == "" ( + set SPHINXBUILD=sphinx-build +) +set BUILDDIR=_build +set ALLSPHINXOPTS=-d %BUILDDIR%/doctrees %SPHINXOPTS% . +if NOT "%PAPER%" == "" ( + set ALLSPHINXOPTS=-D latex_paper_size=%PAPER% %ALLSPHINXOPTS% +) + +if "%1" == "" goto help + +if "%1" == "help" ( + :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. qthelp to make HTML files and a qthelp project + echo. devhelp to make HTML files and a Devhelp project + echo. epub to make an epub + echo. latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter + echo. text to make text files + echo. man to make manual pages + echo. changes to make an overview over 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 + goto end +) + +if "%1" == "clean" ( + for /d %%i in (%BUILDDIR%\*) do rmdir /q /s %%i + del /q /s %BUILDDIR%\* + goto end +) + +if "%1" == "html" ( + %SPHINXBUILD% -b html %ALLSPHINXOPTS% %BUILDDIR%/html + echo. + echo.Build finished. The HTML pages are in %BUILDDIR%/html. + goto end +) + +if "%1" == "dirhtml" ( + %SPHINXBUILD% -b dirhtml %ALLSPHINXOPTS% %BUILDDIR%/dirhtml + echo. + echo.Build finished. The HTML pages are in %BUILDDIR%/dirhtml. + goto end +) + +if "%1" == "singlehtml" ( + %SPHINXBUILD% -b singlehtml %ALLSPHINXOPTS% %BUILDDIR%/singlehtml + echo. + echo.Build finished. The HTML pages are in %BUILDDIR%/singlehtml. + goto end +) + +if "%1" == "pickle" ( + %SPHINXBUILD% -b pickle %ALLSPHINXOPTS% %BUILDDIR%/pickle + echo. + echo.Build finished; now you can process the pickle files. + goto end +) + +if "%1" == "json" ( + %SPHINXBUILD% -b json %ALLSPHINXOPTS% %BUILDDIR%/json + echo. + echo.Build finished; now you can process the JSON files. + goto end +) + +if "%1" == "htmlhelp" ( + %SPHINXBUILD% -b htmlhelp %ALLSPHINXOPTS% %BUILDDIR%/htmlhelp + echo. + echo.Build finished; now you can run HTML Help Workshop with the ^ +.hhp project file in %BUILDDIR%/htmlhelp. + goto end +) + +if "%1" == "qthelp" ( + %SPHINXBUILD% -b qthelp %ALLSPHINXOPTS% %BUILDDIR%/qthelp + echo. + echo.Build finished; now you can run "qcollectiongenerator" with the ^ +.qhcp project file in %BUILDDIR%/qthelp, like this: + echo.^> qcollectiongenerator %BUILDDIR%\qthelp\sphinxcontrib-rubydomain-acceptancetest.qhcp + echo.To view the help file: + echo.^> assistant -collectionFile %BUILDDIR%\qthelp\sphinxcontrib-rubydomain-acceptancetest.ghc + goto end +) + +if "%1" == "devhelp" ( + %SPHINXBUILD% -b devhelp %ALLSPHINXOPTS% %BUILDDIR%/devhelp + echo. + echo.Build finished. + goto end +) + +if "%1" == "epub" ( + %SPHINXBUILD% -b epub %ALLSPHINXOPTS% %BUILDDIR%/epub + echo. + echo.Build finished. The epub file is in %BUILDDIR%/epub. + goto end +) + +if "%1" == "latex" ( + %SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex + echo. + echo.Build finished; the LaTeX files are in %BUILDDIR%/latex. + goto end +) + +if "%1" == "text" ( + %SPHINXBUILD% -b text %ALLSPHINXOPTS% %BUILDDIR%/text + echo. + echo.Build finished. The text files are in %BUILDDIR%/text. + goto end +) + +if "%1" == "man" ( + %SPHINXBUILD% -b man %ALLSPHINXOPTS% %BUILDDIR%/man + echo. + echo.Build finished. The manual pages are in %BUILDDIR%/man. + goto end +) + +if "%1" == "changes" ( + %SPHINXBUILD% -b changes %ALLSPHINXOPTS% %BUILDDIR%/changes + echo. + echo.The overview file is in %BUILDDIR%/changes. + goto end +) + +if "%1" == "linkcheck" ( + %SPHINXBUILD% -b linkcheck %ALLSPHINXOPTS% %BUILDDIR%/linkcheck + echo. + echo.Link check complete; look for any errors in the above output ^ +or in %BUILDDIR%/linkcheck/output.txt. + goto end +) + +if "%1" == "doctest" ( + %SPHINXBUILD% -b doctest %ALLSPHINXOPTS% %BUILDDIR%/doctest + echo. + echo.Testing of doctests in the sources finished, look at the ^ +results in %BUILDDIR%/doctest/output.txt. + goto end +) + +:end diff --git a/test/unit/method.html b/test/unit/method.html new file mode 100644 index 0000000..f826a3a --- /dev/null +++ b/test/unit/method.html @@ -0,0 +1,49 @@ + +
+
+

Simple method

+
+
+ + class + + + Foo + + +
+
+
+
+
Foo::test($a, ...$args)
+
+

Simple test method.

+
+
Parameters:
+
+
    +
  • +

    $args (array) – Associative array

    +
    • +
+
+
+
+
+
+

Cross linking

+ +
+
+
+
diff --git a/test/unit/method.md b/test/unit/method.md new file mode 100644 index 0000000..e7d0c1f --- /dev/null +++ b/test/unit/method.md @@ -0,0 +1,17 @@ +# Simple method + +:::{php:class} Foo +::: + +:::{php:method} test($a, ...$args) + +Simple test method. + +```{eval-rst} +:param array $args: Associative array +``` +::: + +## Cross linking + +- {php:meth}`Foo::test()` diff --git a/test/unit/ns.html b/test/unit/ns.html new file mode 100644 index 0000000..bf0c670 --- /dev/null +++ b/test/unit/ns.html @@ -0,0 +1,51 @@ + +
+
+ +

Simple NS

+
+
+ + class + + + Foo\ + + + A + + +
+
+
+
+
+ + Foo\A:: + + + simplify + + ( + ) + +
+
+
+
+

Cross linking

+ +
+
+
+
diff --git a/test/unit/ns.md b/test/unit/ns.md new file mode 100644 index 0000000..1ebfe4d --- /dev/null +++ b/test/unit/ns.md @@ -0,0 +1,14 @@ +# Simple NS + +:::{php:namespace} Foo +::: + +:::{php:class} A +::: + +:::{php:method} simplify() +::: + +## Cross linking + +- {php:meth}`A::simplify` diff --git a/test/unit/requirements.txt b/test/unit/requirements.txt new file mode 100644 index 0000000..98a3c62 --- /dev/null +++ b/test/unit/requirements.txt @@ -0,0 +1,2 @@ +sphinx +myst-parser