diff --git a/setup.cfg b/.flake8 similarity index 70% rename from setup.cfg rename to .flake8 index dbdc61b9..b7510db2 100644 --- a/setup.cfg +++ b/.flake8 @@ -1,12 +1,6 @@ -[metadata] -license_file = LICENSE - [flake8] max-line-length = 100 exclude = compoundsuper.py,indexsuper.py extend-ignore = E203, E231 per-file-ignores = breathe/parser/index.py:E305 - -[bdist_wheel] -universal = 0 diff --git a/.github/FUNDING.yml b/.github/FUNDING.yml index 0709cc05..c287bfa6 100644 --- a/.github/FUNDING.yml +++ b/.github/FUNDING.yml @@ -1,6 +1,6 @@ # These are supported funding model platforms -github: # Replace with up to 4 GitHub Sponsors-enabled usernames e.g., [user1, user2] +github: breathe-doc patreon: # Replace with a single Patreon username open_collective: breathe ko_fi: # Replace with a single Ko-fi username diff --git a/.github/workflows/documentation.yml b/.github/workflows/documentation.yml index f69712c0..624f3073 100644 --- a/.github/workflows/documentation.yml +++ b/.github/workflows/documentation.yml @@ -7,19 +7,15 @@ jobs: steps: - uses: actions/checkout@v4 - - uses: actions/cache@v3 - with: - path: ~/.cache/pip - key: ${{ runner.os }}-pip-${{ hashFiles('requirements/*.txt') }} - restore-keys: | - ${{ runner.os }}-pip- - name: set up python - uses: actions/setup-python@v4 + uses: actions/setup-python@v5 + with: + cache: 'pip' - name: install dependencies run: | - pip install -r requirements/development.txt + pip install ".[docs]" sudo apt-get -y update sudo apt-get -y install graphviz libclang1-11 libclang-cpp11 diff --git a/.github/workflows/lint.yml b/.github/workflows/lint.yml index df95dfb2..9b054158 100644 --- a/.github/workflows/lint.yml +++ b/.github/workflows/lint.yml @@ -7,18 +7,15 @@ jobs: steps: - uses: actions/checkout@v4 - - uses: actions/cache@v3 - with: - path: ~/.cache/pip - key: ${{ runner.os }}-pip-${{ hashFiles('requirements/*.txt') }} - restore-keys: | - ${{ runner.os }}-pip- + - name: set up python - uses: actions/setup-python@v4 + uses: actions/setup-python@v5 + with: + cache: 'pip' - name: install dependencies run: | - pip install -r requirements/development.txt + pip install ".[lint]" - name: lint the source code run: make flake8 @@ -28,6 +25,3 @@ jobs: - name: type check the source code run: make type-check - - - name: check version numbers are in sync - run: make version-check diff --git a/.github/workflows/unit_tests.yml b/.github/workflows/unit_tests.yml index 4cb17e6a..0c95b400 100644 --- a/.github/workflows/unit_tests.yml +++ b/.github/workflows/unit_tests.yml @@ -7,46 +7,31 @@ jobs: strategy: fail-fast: false matrix: - python-version: ['3.7', '3.8', '3.9', '3.10'] + python-version: + - '3.8' + - '3.9' + - '3.10' + - '3.11' + - '3.12' sphinx-version: - - '4.0.3' - - '4.1.2' - - '4.2.0' - - '4.3.2' - - '4.5.0' - '5.0.2' - '5.1.1' + - '5.2.3' - '5.3.0' - '6.1.3' - git+https://github.com/sphinx-doc/sphinx.git@master - exclude: - # avoid bug in following configurations - # sphinx/util/typing.py:37: in - # from types import Union as types_Union - # ImportError: cannot import name 'Union' from 'types' - - python-version: '3.10' - sphinx-version: '4.0.3' - - python-version: '3.10' - sphinx-version: '4.1.2' - - # Sphinx has removed support for Python 3.7, Breathe will follow. - - python-version: '3.7' - sphinx-version: git+https://github.com/sphinx-doc/sphinx.git@master - - python-version: '3.7' - sphinx-version: '6.1.3' steps: - uses: actions/checkout@v4 - - uses: actions/cache@v3 - with: - path: ~/.cache/pip - key: ${{ runner.os }}-pip-${{ hashFiles('requirements/*.txt') }} - restore-keys: | - ${{ runner.os }}-pip- - name: set up python ${{ matrix.python-version }} - uses: actions/setup-python@v4 + uses: actions/setup-python@v5 with: python-version: ${{ matrix.python-version }} + cache: 'pip' + + - name: install dependencies + run: | + pip install ".[test]" - name: install sphinx from PyPI or from git run: | @@ -56,9 +41,5 @@ jobs: pip install -Iv Sphinx==${{ matrix.sphinx-version }} fi - - name: install dependencies - run: | - pip install -r requirements/development.txt - - name: run the unit tests run: make dev-test diff --git a/Makefile b/Makefile index 8acedb7d..6e5957e8 100644 --- a/Makefile +++ b/Makefile @@ -45,7 +45,3 @@ black: .PHONY: type-check type-check: mypy --warn-redundant-casts --warn-unused-ignores breathe tests - -.PHONY: version-check -version-check: - PYTHONPATH=../:$(PYTHONPATH) python3 scripts/version-check.py diff --git a/README.rst b/README.rst index bfc11d78..cbf01022 100644 --- a/README.rst +++ b/README.rst @@ -98,7 +98,7 @@ branch. Requirements ------------ -Breathe requires Python 3.6+, Sphinx 4.0+ and Doxygen 1.8+. +Breathe requires Python 3.8+, Sphinx 5.0+ and Doxygen 1.8+. Mailing List Archives --------------------- diff --git a/breathe-apidoc.py b/breathe-apidoc.py index a3437812..8aa276e5 100755 --- a/breathe-apidoc.py +++ b/breathe-apidoc.py @@ -1,5 +1,4 @@ #!/usr/bin/env python -# -*- coding: utf-8 -*- import sys diff --git a/breathe/__init__.py b/breathe/__init__.py index b0282794..4864133d 100644 --- a/breathe/__init__.py +++ b/breathe/__init__.py @@ -4,7 +4,6 @@ from sphinx.application import Sphinx -# Keep in sync with setup.py __version__ __version__ = "4.35.0" diff --git a/breathe/apidoc.py b/breathe/apidoc.py index e7ff33eb..19896680 100644 --- a/breathe/apidoc.py +++ b/breathe/apidoc.py @@ -1,4 +1,3 @@ -# -*- coding: utf-8 -*- """ breathe.apidoc ~~~~~~~~~~~~~~ @@ -14,7 +13,6 @@ :copyright: Originally by Sphinx Team, C++ modifications by Tatsuyuki Ishi :license: BSD, see LICENSE for details. """ -from __future__ import print_function import os import sys @@ -24,14 +22,6 @@ from breathe import __version__ -# Account for FileNotFoundError in Python 2 -# IOError is broader but will hopefully suffice -try: - FileNotFoundError -except NameError: - FileNotFoundError = IOError - - # Reference: Doxygen XSD schema file, CompoundKind only # Only what breathe supports are included # Translates identifier to English @@ -71,7 +61,7 @@ def write_file(name, text, args): if exc.errno != errno.EEXIST: raise try: - with open(fname, "r") as target: + with open(fname) as target: orig = target.read() if orig == text: print_info("File %s up to date, skipping." % fname, args) @@ -141,7 +131,7 @@ def recurse_tree(args): class TypeAction(argparse.Action): def __init__(self, option_strings, dest, **kwargs): - super(TypeAction, self).__init__(option_strings, dest, **kwargs) + super().__init__(option_strings, dest, **kwargs) self.default = TYPEDICT.keys() self.metavar = ",".join(TYPEDICT.keys()) diff --git a/breathe/parser/compound.py b/breathe/parser/compound.py index da6ee69b..cf858d7d 100644 --- a/breathe/parser/compound.py +++ b/breathe/parser/compound.py @@ -927,7 +927,7 @@ def __init__(self, char=None, valueOf_=''): # end class docCharTypeSub -class verbatimTypeSub(object): +class verbatimTypeSub: """ New node type. Structure is largely pillaged from other nodes in order to match the set. @@ -1200,7 +1200,7 @@ def parse(inFilename): try: doc = minidom.parse(inFilename) - except IOError as e: + except OSError as e: raise FileIOError(e) except ExpatError as e: raise ParseError(e) diff --git a/breathe/parser/compoundsuper.py b/breathe/parser/compoundsuper.py index 79050edd..3c01da9c 100644 --- a/breathe/parser/compoundsuper.py +++ b/breathe/parser/compoundsuper.py @@ -134,7 +134,7 @@ def getName(self): return self.name -class _MemberSpec(object): +class _MemberSpec: def __init__(self, name='', data_type='', container=0): self.name = name self.data_type = data_type @@ -2632,7 +2632,7 @@ def buildChildren(self, child_, nodeName_): value_.append(text_.nodeValue) # We make this unicode so that our unicode renderer catch-all picks it up # otherwise it would go through as 'str' and we'd have to pick it up too - valuestr_ = u' ' + valuestr_ = ' ' obj_ = self.mixedclass_(MixedContainer.CategorySimple, MixedContainer.TypeString, 'sp', valuestr_) self.content_.append(obj_) diff --git a/breathe/parser/index.py b/breathe/parser/index.py index 3788991e..d4f0634b 100644 --- a/breathe/parser/index.py +++ b/breathe/parser/index.py @@ -49,7 +49,7 @@ class FileIOError(Exception): def parse(inFilename): try: doc = minidom.parse(inFilename) - except IOError as e: + except OSError as e: raise FileIOError(e) except ExpatError as e: raise ParseError(e) diff --git a/breathe/parser/indexsuper.py b/breathe/parser/indexsuper.py index 4c7126ce..8f748455 100644 --- a/breathe/parser/indexsuper.py +++ b/breathe/parser/indexsuper.py @@ -129,7 +129,7 @@ def getName(self): return self.name -class _MemberSpec(object): +class _MemberSpec: def __init__(self, name='', data_type='', container=0): self.name = name self.data_type = data_type diff --git a/breathe/project.py b/breathe/project.py index 865236e8..5c2b65d3 100644 --- a/breathe/project.py +++ b/breathe/project.py @@ -110,10 +110,9 @@ def __init__(self, app: Sphinx): self.app = app # note: don't access self.app.config now, as we are instantiated at setup-time. - # Assume general build directory is the doctree directory without the last component. - # We strip off any trailing slashes so that dirname correctly drops the last part. + # Assume general build directory is the parent of the doctree directory. # This can be overridden with the breathe_build_directory config variable - self._default_build_dir = os.path.dirname(app.doctreedir.rstrip(os.sep)) + self._default_build_dir = os.path.dirname(os.path.normpath(app.doctreedir)) self.project_count = 0 self.project_info_store: Dict[str, ProjectInfo] = {} self.project_info_for_auto_store: Dict[str, AutoProjectInfo] = {} diff --git a/breathe/renderer/sphinxrenderer.py b/breathe/renderer/sphinxrenderer.py index dff0c982..a87fe0f2 100644 --- a/breathe/renderer/sphinxrenderer.py +++ b/breathe/renderer/sphinxrenderer.py @@ -2402,12 +2402,9 @@ def visit_docdotfile(self, node) -> List[Node]: # Use self.project_info.project_path as the XML_OUTPUT path, and # make it absolute with consideration to the conf.py path project_path = self.project_info.project_path() - if os.path.isabs(project_path): - dot_file_path = os.path.abspath(project_path + os.sep + dot_file_path) - else: - dot_file_path = os.path.abspath( - self.app.confdir + os.sep + project_path + os.sep + dot_file_path - ) + dot_file_path = os.path.abspath( + os.path.join(self.app.confdir, project_path, dot_file_path) + ) try: with open(dot_file_path, encoding="utf-8") as fp: dotcode = fp.read() diff --git a/documentation/environment.yaml b/documentation/environment.yaml index 9d1fb09d..3f019f13 100644 --- a/documentation/environment.yaml +++ b/documentation/environment.yaml @@ -11,4 +11,4 @@ dependencies: - doxygen - pip - pip: - - -r ../requirements/development.txt + - ".[docs,lint,test]" diff --git a/documentation/make.bat b/documentation/make.bat new file mode 100644 index 00000000..21f97a1c --- /dev/null +++ b/documentation/make.bat @@ -0,0 +1,243 @@ +@ECHO OFF + +REM Command file for Sphinx documentation + +if "%SPHINXBUILD%" == "" ( + set SPHINXBUILD=sphinx-build +) +set BUILDDIR=build +set SRCDIR=source +set ALLSPHINXOPTS=-d %BUILDDIR%/doctrees %SPHINXOPTS% %SRCDIR% +set I18NSPHINXOPTS=%SPHINXOPTS% %SRCDIR% +if NOT "%PAPER%" == "" ( + set ALLSPHINXOPTS=-D latex_paper_size=%PAPER% %ALLSPHINXOPTS% + set I18NSPHINXOPTS=-D latex_paper_size=%PAPER% %I18NSPHINXOPTS% +) + +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. texinfo to make Texinfo files + echo. gettext to make PO message catalogs + echo. changes to make an overview over all changed/added/deprecated items + echo. xml to make Docutils-native XML files + echo. pseudoxml to make pseudoxml-XML files for display purposes + 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 +) + + +%SPHINXBUILD% 2> nul +if errorlevel 9009 ( + echo. + echo.The 'sphinx-build' command was not found. Make sure you have Sphinx + echo.installed, then set the SPHINXBUILD environment variable to point + echo.to the full path of the 'sphinx-build' executable. Alternatively you + echo.may add the Sphinx directory to PATH. + echo. + echo.If you don't have Sphinx installed, grab it from + echo.http://sphinx-doc.org/ + exit /b 1 +) + +if "%1" == "html" ( + %SPHINXBUILD% -b html %ALLSPHINXOPTS% %BUILDDIR%/html + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The HTML pages are in %BUILDDIR%/html. + goto end +) + +if "%1" == "dirhtml" ( + %SPHINXBUILD% -b dirhtml %ALLSPHINXOPTS% %BUILDDIR%/dirhtml + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The HTML pages are in %BUILDDIR%/dirhtml. + goto end +) + +if "%1" == "singlehtml" ( + %SPHINXBUILD% -b singlehtml %ALLSPHINXOPTS% %BUILDDIR%/singlehtml + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The HTML pages are in %BUILDDIR%/singlehtml. + goto end +) + +if "%1" == "pickle" ( + %SPHINXBUILD% -b pickle %ALLSPHINXOPTS% %BUILDDIR%/pickle + if errorlevel 1 exit /b 1 + echo. + echo.Build finished; now you can process the pickle files. + goto end +) + +if "%1" == "json" ( + %SPHINXBUILD% -b json %ALLSPHINXOPTS% %BUILDDIR%/json + if errorlevel 1 exit /b 1 + echo. + echo.Build finished; now you can process the JSON files. + goto end +) + +if "%1" == "htmlhelp" ( + %SPHINXBUILD% -b htmlhelp %ALLSPHINXOPTS% %BUILDDIR%/htmlhelp + if errorlevel 1 exit /b 1 + 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 + if errorlevel 1 exit /b 1 + echo. + echo.Build finished; now you can run "qcollectiongenerator" with the ^ +.qhcp project file in %BUILDDIR%/qthelp, like this: + echo.^> qcollectiongenerator %BUILDDIR%\qthelp\libuv.qhcp + echo.To view the help file: + echo.^> assistant -collectionFile %BUILDDIR%\qthelp\libuv.ghc + goto end +) + +if "%1" == "devhelp" ( + %SPHINXBUILD% -b devhelp %ALLSPHINXOPTS% %BUILDDIR%/devhelp + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. + goto end +) + +if "%1" == "epub" ( + %SPHINXBUILD% -b epub %ALLSPHINXOPTS% %BUILDDIR%/epub + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The epub file is in %BUILDDIR%/epub. + goto end +) + +if "%1" == "latex" ( + %SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex + if errorlevel 1 exit /b 1 + echo. + echo.Build finished; the LaTeX files are in %BUILDDIR%/latex. + goto end +) + +if "%1" == "latexpdf" ( + %SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex + cd %BUILDDIR%/latex + make all-pdf + cd %BUILDDIR%/.. + echo. + echo.Build finished; the PDF files are in %BUILDDIR%/latex. + goto end +) + +if "%1" == "latexpdfja" ( + %SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex + cd %BUILDDIR%/latex + make all-pdf-ja + cd %BUILDDIR%/.. + echo. + echo.Build finished; the PDF files are in %BUILDDIR%/latex. + goto end +) + +if "%1" == "text" ( + %SPHINXBUILD% -b text %ALLSPHINXOPTS% %BUILDDIR%/text + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The text files are in %BUILDDIR%/text. + goto end +) + +if "%1" == "man" ( + %SPHINXBUILD% -b man %ALLSPHINXOPTS% %BUILDDIR%/man + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The manual pages are in %BUILDDIR%/man. + goto end +) + +if "%1" == "texinfo" ( + %SPHINXBUILD% -b texinfo %ALLSPHINXOPTS% %BUILDDIR%/texinfo + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The Texinfo files are in %BUILDDIR%/texinfo. + goto end +) + +if "%1" == "gettext" ( + %SPHINXBUILD% -b gettext %I18NSPHINXOPTS% %BUILDDIR%/locale + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The message catalogs are in %BUILDDIR%/locale. + goto end +) + +if "%1" == "changes" ( + %SPHINXBUILD% -b changes %ALLSPHINXOPTS% %BUILDDIR%/changes + if errorlevel 1 exit /b 1 + echo. + echo.The overview file is in %BUILDDIR%/changes. + goto end +) + +if "%1" == "linkcheck" ( + %SPHINXBUILD% -b linkcheck %ALLSPHINXOPTS% %BUILDDIR%/linkcheck + if errorlevel 1 exit /b 1 + 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 + if errorlevel 1 exit /b 1 + echo. + echo.Testing of doctests in the sources finished, look at the ^ +results in %BUILDDIR%/doctest/output.txt. + goto end +) + +if "%1" == "xml" ( + %SPHINXBUILD% -b xml %ALLSPHINXOPTS% %BUILDDIR%/xml + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The XML files are in %BUILDDIR%/xml. + goto end +) + +if "%1" == "pseudoxml" ( + %SPHINXBUILD% -b pseudoxml %ALLSPHINXOPTS% %BUILDDIR%/pseudoxml + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The pseudo-XML files are in %BUILDDIR%/pseudoxml. + goto end +) + +:end \ No newline at end of file diff --git a/documentation/source/conf.py b/documentation/source/conf.py index c1cf8c34..a0868216 100644 --- a/documentation/source/conf.py +++ b/documentation/source/conf.py @@ -1,5 +1,3 @@ -# -*- coding: utf-8 -*- -# # BreatheExample documentation build configuration file, created by # sphinx-quickstart on Tue Feb 3 18:20:48 2009. # @@ -35,6 +33,7 @@ "sphinx.ext.ifconfig", "sphinx.ext.graphviz", "sphinx_copybutton", + "sphinxcontrib.spelling", ] read_the_docs_build = os.environ.get("READTHEDOCS", None) == "True" @@ -122,17 +121,6 @@ version = "compare" release = "compare" -# Only add spelling extension if it is available. We don't know if it is installed as we don't want -# to put it in the setup.py file as a dependency as we don't want Breathe to be dependent on it as -# people should be able to use Breathe without 'spelling'. There might be a better way to handle -# this. -try: - import sphinxcontrib.spelling - - extensions.append("sphinxcontrib.spelling") -except ImportError: - pass - # Configuration for spelling extension spelling_word_list_filename = "spelling_wordlist.txt" diff --git a/examples/doxygen/make.bat b/examples/doxygen/make.bat new file mode 100644 index 00000000..120e9b22 --- /dev/null +++ b/examples/doxygen/make.bat @@ -0,0 +1,111 @@ +@ECHO OFF + +set DOXYGEN=doxygen +for /f "delims=" %%i in ('where doxygen') do set DOXYGEN=%%i + +set PERL=perl +for /f "delims=" %%i in ('where perl') do set PERL=%%i + +set HAVE_DOT=dot +for /f "delims=" %%i in ('where dot') do set HAVE_DOT=%%i + +@REM echo DOXYGEN : %DOXYGEN% +@REM echo PERL : %PERL% +@REM echo HAVE_DOT : %HAVE_DOT% + +if "%1" == "" ( + call :all + goto end +) + +if "%1" == "all" ( + call :all + goto end +) + +if "%1" == "clean" ( + call :clean + goto end +) + +goto end + +:all + call :doxygen class.cfg + call :doxygen concept.cfg + call :doxygen define.cfg + call :doxygen enum.cfg + call :doxygen file.cfg + call :doxygen func.cfg + call :doxygen page.cfg + call :doxygen relates.cfg + call :doxygen author.cfg + call :doxygen par.cfg + call :doxygen parblock.cfg + call :doxygen overload.cfg + call :doxygen example.cfg + call :doxygen include.cfg + call :doxygen qtstyle.cfg + call :doxygen jdstyle.cfg + call :doxygen structcmd.cfg + call :doxygen autolink.cfg + call :doxygen restypedef.cfg + call :doxygen afterdoc.cfg + call :doxygen templ.cfg + call :doxygen tag.cfg + call :doxygen group.cfg + call :doxygen diagrams.cfg + call :doxygen memgrp.cfg + call :doxygen docstring.cfg + call :doxygen pyexample.cfg + call :doxygen manual.cfg + call :doxygen interface.cfg + goto end + +:clean + call :rmdir class + call :rmdir concept + call :rmdir define + call :rmdir enum + call :rmdir file + call :rmdir func + call :rmdir page + call :rmdir relates + call :rmdir author + call :rmdir par + call :rmdir parblock + call :rmdir overload + call :rmdir example + call :rmdir include + call :rmdir qtstyle + call :rmdir jdstyle + call :rmdir structcmd + call :rmdir autolink + call :rmdir restypedef + call :rmdir afterdoc + call :rmdir template + call :rmdir tag + call :rmdir group + call :rmdir diagrams + call :rmdir memgrp + call :rmdir docstring + call :rmdir pyexample + call :rmdir manual + call :rmdir interface + goto end + +:doxygen + set CFG=%~1 + echo Running doxygen: %CFG% + "%DOXYGEN%" %CFG% + goto end + +:rmdir + set DIR=%~1 + if exist "%DIR%" ( + echo Removing directory: %DIR% + rmdir /s/q "%DIR%" + ) + goto end + +:end \ No newline at end of file diff --git a/examples/specific/make.bat b/examples/specific/make.bat new file mode 100644 index 00000000..f8a57423 --- /dev/null +++ b/examples/specific/make.bat @@ -0,0 +1,183 @@ +@ECHO OFF + +set DOXYGEN=doxygen +for /f "delims=" %%i in ('where doxygen') do set DOXYGEN=%%i + +set PERL=perl +for /f "delims=" %%i in ('where perl') do set PERL=%%i + +set HAVE_DOT=dot +for /f "delims=" %%i in ('where dot') do set HAVE_DOT=%%i + +@REM echo DOXYGEN : %DOXYGEN% +@REM echo PERL : %PERL% +@REM echo HAVE_DOT : %HAVE_DOT% + +if "%1" == "" ( + call :all + goto end +) + +if "%1" == "all" ( + call :all + goto end +) + +if "%1" == "clean" ( + call :clean + goto end +) + +goto end + +:all + @REM --------------- + @REM General Pattern + @REM --------------- + call :doxygen nutshell.cfg + call :doxygen alias.cfg + call :doxygen rst.cfg + call :doxygen inline.cfg + call :doxygen namespacefile.cfg + call :doxygen array.cfg + call :doxygen inheritance.cfg + call :doxygen members.cfg + call :doxygen userdefined.cfg + call :doxygen fixedwidthfont.cfg + call :doxygen latexmath.cfg + call :doxygen functionOverload.cfg + call :doxygen image.cfg + call :doxygen name.cfg + call :doxygen union.cfg + call :doxygen group.cfg + call :doxygen struct.cfg + call :doxygen struct_function.cfg + call :doxygen qtsignalsandslots.cfg + call :doxygen lists.cfg + call :doxygen headings.cfg + call :doxygen links.cfg + call :doxygen parameters.cfg + call :doxygen template_class.cfg + call :doxygen template_class_non_type.cfg + call :doxygen template_function.cfg + call :doxygen template_type_alias.cfg + call :doxygen template_specialisation.cfg + call :doxygen enum.cfg + call :doxygen define.cfg + call :doxygen interface.cfg + call :doxygen xrefsect.cfg + call :doxygen tables.cfg + call :doxygen cpp_anon.cfg + call :doxygen cpp_concept.cfg + call :doxygen cpp_enum.cfg + call :doxygen cpp_union.cfg + call :doxygen cpp_function.cfg + call :doxygen cpp_friendclass.cfg + call :doxygen cpp_inherited_members.cfg + call :doxygen cpp_trailing_return_type.cfg + call :doxygen cpp_constexpr_hax.cfg + call :doxygen cpp_function_lookup.cfg + call :doxygen c_file.cfg + call :doxygen c_struct.cfg + call :doxygen c_enum.cfg + call :doxygen c_typedef.cfg + call :doxygen c_macro.cfg + call :doxygen c_union.cfg + call :doxygen membergroups.cfg + call :doxygen simplesect.cfg + call :doxygen code_blocks.cfg + call :doxygen dot_graphs.cfg + @REM ------------- + @REM Special Cases + @REM ------------- + call :doxygen programlisting.cfg + call :doxygen decl_impl.cfg + call :doxygen multifile.cfg + call :doxygen auto.cfg + call :doxygen class.cfg + call :doxygen typedef.cfg + goto end + +:clean + @REM --------------- + @REM General Pattern + @REM --------------- + call :rmdir nutshell + call :rmdir alias + call :rmdir rst + call :rmdir inline + call :rmdir namespacefile + call :rmdir array + call :rmdir inheritance + call :rmdir members + call :rmdir userdefined + call :rmdir fixedwidthfont + call :rmdir latexmath + call :rmdir functionOverload + call :rmdir image + call :rmdir name + call :rmdir union + call :rmdir group + call :rmdir struct + call :rmdir struct_function + call :rmdir qtsignalsandslots + call :rmdir lists + call :rmdir headings + call :rmdir links + call :rmdir parameters + call :rmdir template_class + call :rmdir template_class_non_type + call :rmdir template_function + call :rmdir template_type_alias + call :rmdir template_specialisation + call :rmdir enum + call :rmdir define + call :rmdir interface + call :rmdir xrefsect + call :rmdir tables + call :rmdir cpp_anon + call :rmdir cpp_concept + call :rmdir cpp_enum + call :rmdir cpp_union + call :rmdir cpp_function + call :rmdir cpp_friendclass + call :rmdir cpp_inherited_members + call :rmdir cpp_trailing_return_type + call :rmdir cpp_constexpr_hax + call :rmdir cpp_function_lookup + call :rmdir c_file + call :rmdir c_struct + call :rmdir c_enum + call :rmdir c_typedef + call :rmdir c_macro + call :rmdir c_union + call :rmdir membergroups + call :rmdir simplesect + call :rmdir code_blocks + call :rmdir dot_graphs + @REM ------------- + @REM Special Cases + @REM ------------- + call :rmdir programlisting + call :rmdir decl_impl + call :rmdir multifilexml + call :rmdir auto + call :rmdir class + call :rmdir typedef + goto end + +:doxygen + set CFG=%~1 + echo Running doxygen: %CFG% + "%DOXYGEN%" %CFG% + goto end + +:rmdir + set DIR=%~1 + if exist "%DIR%" ( + echo Removing directory: %DIR% + rmdir /s/q "%DIR%" + ) + goto end + +:end \ No newline at end of file diff --git a/examples/tinyxml/make.bat b/examples/tinyxml/make.bat new file mode 100644 index 00000000..66f01a8c --- /dev/null +++ b/examples/tinyxml/make.bat @@ -0,0 +1,55 @@ +@ECHO OFF + +set DOXYGEN=doxygen +for /f "delims=" %%i in ('where doxygen') do set DOXYGEN=%%i + +set PERL=perl +for /f "delims=" %%i in ('where perl') do set PERL=%%i + +set HAVE_DOT=dot +for /f "delims=" %%i in ('where dot') do set HAVE_DOT=%%i + +@REM echo DOXYGEN : %DOXYGEN% +@REM echo PERL : %PERL% +@REM echo HAVE_DOT : %HAVE_DOT% + +if "%1" == "" ( + call :all + goto end +) + +if "%1" == "all" ( + call :all + goto end +) + +if "%1" == "clean" ( + call :clean + goto end +) + +goto end + +:all + call :doxygen tinyxml.cfg + goto end + +:clean + call :rmdir tinyxml + goto end + +:doxygen + set CFG=%~1 + echo Running doxygen: %CFG% + "%DOXYGEN%" %CFG% + goto end + +:rmdir + set DIR=%~1 + if exist "%DIR%" ( + echo Removing directory: %DIR% + rmdir /s/q "%DIR%" + ) + goto end + +:end \ No newline at end of file diff --git a/make.bat b/make.bat new file mode 100644 index 00000000..b68c75be --- /dev/null +++ b/make.bat @@ -0,0 +1,97 @@ +@ECHO OFF + +if "%1" == "html" goto html +if "%1" == "pdf" goto pdf +if "%1" == "data" goto data +if "%1" == "clean" goto clean +if "%1" == "distclean" goto distclean +if "%1" == "test" goto test +if "%1" == "dev-test" goto dev-test +if "%1" == "flake8" goto flake8 +if "%1" == "black" goto black +if "%1" == "type-check" goto type-check +if "%1" == "version-check" goto version-check +if "%1" == "all" goto all +goto end + +:html + call :data + cd documentation + call make.bat html + cd .. + goto end + +:pdf + call :data + cd documentation + call make.bat latexpdf + cd .. + goto end + +:data + cd examples\doxygen + call make.bat all + cd ..\.. + cd examples\tinyxml + call make.bat all + cd ..\.. + cd examples\specific + call make.bat all + cd ..\.. + goto end + +:clean + cd examples\doxygen + call make.bat clean + cd ..\.. + cd examples\tinyxml + call make.bat clean + cd ..\.. + cd examples\specific + call make.bat clean + cd ..\.. + goto end + +:distclean + call :clean + cd documentation + call make.bat clean + cd .. + goto end + +:test + cd tests + python -m pytest -v + cd .. + goto end + +:dev-test + cd tests + set PYTHONPATH=..\;%PYTHONPATH% + python -m pytest -v + cd .. + goto end + +:flake8 + flake8 breathe + goto end + +:black + black --check . + goto end + +:type-check + mypy --warn-redundant-casts --warn-unused-ignores breathe tests + goto end + +:version-check + set PYTHONPATH=..\;%PYTHONPATH% + python scripts\version-check.py + goto end + +:all + call :html + call :pdf + goto end + +:end \ No newline at end of file diff --git a/mkrelease b/mkrelease index 545a75fa..c0a95c84 100755 --- a/mkrelease +++ b/mkrelease @@ -40,7 +40,7 @@ pack() tar -xf "breathe-$version.tar.gz" cd -- "breathe-$version" - python3 setup.py sdist bdist_wheel + python3 -m build mv -- dist .. cd -- .. @@ -66,6 +66,7 @@ upload() ( cd -- mkrelease_tmp + twine check --strict dist/* twine upload -- dist/* { diff --git a/pyproject.toml b/pyproject.toml index 15f421bb..1f21f7a5 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -1,3 +1,102 @@ +[build-system] +requires = ["flit_core>=3.7"] +build-backend = "flit_core.buildapi" + +# project metadata +[project] +name = "breathe" +description = "Sphinx Doxygen renderer" +readme = "README.rst" +urls.Changelog = "https://github.com/breathe-doc/breathe/blob/main/CHANGELOG.rst" +urls.Code = "https://github.com/breathe-doc/breathe/" +urls.Download = "https://pypi.org/project/breathe/" +urls.Documentation = "https://breathe.readthedocs.io/" +urls.Homepage = "https://www.breathe-doc.org/" +urls."Issue tracker" = "https://github.com/breathe-doc/breathe/issues" +license.text = "BSD-3-Clause" +requires-python = ">=3.8" + +# Classifiers list: https://pypi.org/classifiers/ +classifiers = [ + "Development Status :: 5 - Production/Stable", + "Environment :: Console", + "Environment :: Web Environment", + "Framework :: Sphinx", + "Framework :: Sphinx :: Extension", + "Intended Audience :: Developers", + "Intended Audience :: Education", + "License :: OSI Approved :: BSD License", + "Operating System :: OS Independent", + "Programming Language :: Python", + "Programming Language :: Python :: 3", + "Programming Language :: Python :: 3 :: Only", + "Programming Language :: Python :: 3.8", + "Programming Language :: Python :: 3.9", + "Programming Language :: Python :: 3.10", + "Programming Language :: Python :: 3.11", + "Programming Language :: Python :: 3.12", + "Programming Language :: Python :: 3.13", + "Topic :: Documentation", + "Topic :: Documentation :: Sphinx", + "Topic :: Software Development", + "Topic :: Software Development :: Documentation", + "Topic :: Text Processing", + "Topic :: Utilities", +] +dependencies = [ + "Sphinx>=5.0.2", + "docutils>=0.12", + "Jinja2>=2.7.3", + "MarkupSafe>=0.23", + "Pygments>=1.6", +] +dynamic = ["version"] + +[project.optional-dependencies] +docs = [ + "furo", + "sphinx-copybutton", + "sphinxcontrib-spelling", +] +lint = [ + "black==22.3.0", + "flake8>=6.0", + "mypy>=1", + "types-docutils", + "types-Pygments", +] +test = [ + "pytest>=8.0", +] + +[[project.authors]] +name = "Michael Jones" +email = "m.pricejones@gmail.com" + +[project.scripts] +breathe-apidoc = "breathe.apidoc:main" + +[tool.flit.module] +name = "breathe" + +[tool.flit.sdist] +include = [ + "LICENSE", + "CHANGELOG.rst", + "CONTRIBUTING.rst", + "CONTRIBUTORS.rst", + # Documentation + "documentation/", + # Tests + "tests/", + # Utilities + "Makefile", + "mkrelease", +] +exclude = [ + "documentation/build", +] + [tool.black] line-length = 100 extend-exclude = ''' diff --git a/requirements/development.txt b/requirements/development.txt deleted file mode 100644 index 35b1c56d..00000000 --- a/requirements/development.txt +++ /dev/null @@ -1,14 +0,0 @@ --r production.txt - -flake8 -pip-tools>=0.3.5 -pytest - -mypy>=0.900 -types-docutils>=0.14,<0.18 -types-Pygments - -black==22.3.0 - -sphinx-copybutton -furo \ No newline at end of file diff --git a/requirements/production.txt b/requirements/production.txt deleted file mode 100644 index 816dbe45..00000000 --- a/requirements/production.txt +++ /dev/null @@ -1,5 +0,0 @@ -docutils>=0.12 -Jinja2>=2.7.3 -MarkupSafe>=0.23 -Pygments>=1.6 -Sphinx>=4.0,!=5.0.0 diff --git a/scripts/version-check.py b/scripts/version-check.py deleted file mode 100644 index 2ad59ccb..00000000 --- a/scripts/version-check.py +++ /dev/null @@ -1,28 +0,0 @@ -""" -This script is designed to check that the version numbers that we have in place stay in sync. The -script fails with exit code 1 if they are not the same and always prints the current status. -""" - -import sys -import re - -import breathe - -setup_version = "" -with open("setup.py") as setup: - for line in setup: - if line.startswith("__version__"): - match = re.search('"(?P[^"]*)"', line) - if match: - setup_version = match.group("version") - -if setup_version == breathe.__version__: - print("Versions match") - print(f" {setup_version}") - print(f" {breathe.__version__}") - sys.exit(0) -else: - print("Versions do not match") - print(f" {setup_version}") - print(f" {breathe.__version__}") - sys.exit(1) diff --git a/setup.py b/setup.py deleted file mode 100644 index eed8907d..00000000 --- a/setup.py +++ /dev/null @@ -1,61 +0,0 @@ -# -*- coding: utf-8 -*- -try: - from setuptools import setup, find_packages -except ImportError: - import distribute_setup - - distribute_setup.use_setuptools() - from setuptools import setup, find_packages - -import sys - -# Keep in sync with breathe/__init__.py __version__ -__version__ = "4.35.0" - -long_desc = """ -Breathe is an extension to reStructuredText and Sphinx to be able to read and - render `Doxygen `__ xml output. -""" - -requires = ["Sphinx>=4.0,!=5.0.0", "docutils>=0.12"] - -if sys.version_info < (3, 7): - print("ERROR: Sphinx requires at least Python 3.7 to run.") - sys.exit(1) - - -setup( - name="breathe", - version=__version__, - url="https://github.com/michaeljones/breathe", - download_url="https://github.com/michaeljones/breathe", - license="BSD", - author="Michael Jones", - author_email="m.pricejones@gmail.com", - description="Sphinx Doxygen renderer", - long_description=long_desc, - zip_safe=False, - classifiers=[ - "Development Status :: 4 - Beta", - "Environment :: Console", - "Environment :: Web Environment", - "Framework :: Sphinx :: Extension", - "Intended Audience :: Developers", - "Intended Audience :: Education", - "License :: OSI Approved :: BSD License", - "Operating System :: OS Independent", - "Programming Language :: Python :: 3", - "Topic :: Documentation", - "Topic :: Text Processing", - "Topic :: Utilities", - ], - platforms="any", - packages=find_packages(), - include_package_data=True, - entry_points={ - "console_scripts": [ - "breathe-apidoc = breathe.apidoc:main", - ], - }, - install_requires=requires, -) diff --git a/tests/test_renderer.py b/tests/test_renderer.py index a858c65d..0fd044a5 100644 --- a/tests/test_renderer.py +++ b/tests/test_renderer.py @@ -35,7 +35,7 @@ def app(test_params, app_params, make_app, shared_result): """ args, kwargs = app_params assert "srcdir" in kwargs - kwargs["srcdir"].makedirs(exist_ok=True) + os.makedirs(kwargs["srcdir"], exist_ok=True) (kwargs["srcdir"] / "conf.py").write_text("") app_ = make_app(*args, **kwargs) yield app_ diff --git a/tests/warnings/source/conf.py b/tests/warnings/source/conf.py index 3dfc126d..7dde9c8b 100644 --- a/tests/warnings/source/conf.py +++ b/tests/warnings/source/conf.py @@ -1,5 +1,3 @@ -# -*- coding: utf-8 -*- -# # Test Breathe Warnings documentation build configuration file, created by # sphinx-quickstart on Thu Jun 5 18:57:21 2014. #