From 5a9bb07fcda19a257ba6efb4ffe6adea58bd676a Mon Sep 17 00:00:00 2001 From: Mike Taves Date: Fri, 19 Jan 2024 20:33:56 +1300 Subject: [PATCH] Update docs (#298) * Rename reStructuredText files with *.rst suffix * Refresh with a modern sphinx-quickstart run * Move docs/source/changes.rst to CHANGES.rst * Use sphinx-issues for CHANGES.rst, make corrections * Move recent changes from README.md to CHANGES.rst * Add miscellaneous documentation for exceptions and finder module --- .gitignore | 2 + .pre-commit-config.yaml | 1 + docs/source/changes.txt => CHANGES.rst | 55 +++-- MANIFEST.in | 2 +- README.md | 27 +-- docs/requirements.txt | 1 + docs/source/changes.rst | 6 + docs/source/{class.txt => class.rst} | 0 docs/source/conf.py | 207 ++---------------- docs/source/{history.txt => history.rst} | 0 docs/source/{index.txt => index.rst} | 1 + docs/source/{install.txt => install.rst} | 0 docs/source/misc.rst | 16 ++ .../{performance.txt => performance.rst} | 0 docs/source/{tutorial.txt => tutorial.rst} | 0 pyproject.toml | 1 + rtree/finder.py | 5 +- 17 files changed, 91 insertions(+), 233 deletions(-) rename docs/source/changes.txt => CHANGES.rst (67%) create mode 100644 docs/source/changes.rst rename docs/source/{class.txt => class.rst} (100%) rename docs/source/{history.txt => history.rst} (100%) rename docs/source/{index.txt => index.rst} (99%) rename docs/source/{install.txt => install.rst} (100%) create mode 100644 docs/source/misc.rst rename docs/source/{performance.txt => performance.rst} (100%) rename docs/source/{tutorial.txt => tutorial.rst} (100%) diff --git a/.gitignore b/.gitignore index 84ba9f6c..4c7b47d3 100644 --- a/.gitignore +++ b/.gitignore @@ -10,3 +10,5 @@ lib .coverage .tox wheelhouse +.vscode/ +*venv* diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index dc6f78b0..3ac22aba 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -17,3 +17,4 @@ repos: rev: v1.5.1 hooks: - id: mypy + exclude: 'docs/.' diff --git a/docs/source/changes.txt b/CHANGES.rst similarity index 67% rename from docs/source/changes.txt rename to CHANGES.rst index f24c4d58..389ca4ba 100644 --- a/docs/source/changes.txt +++ b/CHANGES.rst @@ -1,38 +1,59 @@ -.. _changes: +1.1.0: 2023-10-17 +================= + +- Python 3.8+ is now required (:PR:`273`) +- Move project metadata to pyproject.toml (:PR:`269`) +- Refactor built wheels for PyPI (:PR:`276`) +- Fix memory leak when breaking mid-way in _get_objects and _get_ids (:PR:`266`) (thanks :user:`akariv`!) -Changes -.............................................................................. +1.0.1: 2022-10-12 +================= + +- Fix up type hints :PR:`243` (thanks :user:`oderby`) +- Python 3.11 wheels :PR:`250` (thanks :user:`ewouth`) + +1.0.0: 2022-04-05 +================= + +- Python 3.7+ is now required (:PR:`212`) (thanks :user:`adamjstewart`!) +- Type hints (:PR:`215` and others) (thanks :user:`adamjstewart`!) +- Python 3.10 wheels, including osx-arm64 :PR:`224` +- Clean up libspatialindex C API mismatches :PR:`222` (thanks :user:`musicinmybrain`!) +- Many doc updates, fixes, and type hints (thanks :user:`adamjstewart`!) :PR:`212` :PR:`221` :PR:`217` :PR:`215` +- __len__ method for index :PR:`194` +- Prevent get_coordinate_pointers from mutating inputs #205 (thanks :user:`sjones94549`!) +- linux-aarch64 wheels :PR:`183` (thanks :user:`odidev`!) +- black (:PR:`218`) and flake8 (:PR:`145`) linting 0.9.3: 2019-12-10 ================= -- find_library and libspatialindex library loading https://github.com/Toblerity/rtree/pull/131 +- find_library and libspatialindex library loading :PR:`131` 0.9.2: 2019-12-09 ================= -- Refactored tests to be based on unittest https://github.com/Toblerity/rtree/pull/129 -- Update libspatialindex library loading code to adapt previous behavior https://github.com/Toblerity/rtree/pull/128 -- Empty data streams throw exceptions and do not partially construct indexes https://github.com/Toblerity/rtree/pull/127 +- Refactored tests to be based on unittest :PR:`129` +- Update libspatialindex library loading code to adapt previous behavior :PR:`128` +- Empty data streams throw exceptions and do not partially construct indexes :PR:`127` 0.9.0: 2019-11-24 ================= - Add Index.GetResultSetOffset() -- Add Index.contains() method for object and id (requires libspatialindex 1.9.3+) #116 -- Add Index.Flush() #107 -- Add TPRTree index support (thanks @sdhiscocks #117 ) -- Return container sizes without returning objects #90 -- Add set_result_limit and set_result_offset for Index paging 44ad21aecd3f7b49314b9be12f3334d8bae7e827 +- Add Index.contains() method for object and id (requires libspatialindex 1.9.3+) :PR:`116` +- Add Index.Flush() :PR:`107` +- Add TPRTree index support (thanks :user:`sdhiscocks` :PR:`117`) +- Return container sizes without returning objects :PR:`90` +- Add set_result_limit and set_result_offset for Index paging :commit:`44ad21aecd3f7b49314b9be12f3334d8bae7e827` Bug fixes: -- Better exceptions in cases where stream functions throw #80 +- Better exceptions in cases where stream functions throw :PR:`80` - Migrated CI platform to Azure Pipelines https://dev.azure.com/hobuinc/rtree/_build?definitionId=5 - Minor test enhancements and fixups. Both libspatialindex 1.8.5 and libspatialindex 1.9.3 are tested with CI - 0.8: 2014-07-17 =============== @@ -69,7 +90,7 @@ Bug fixes: - Many more docstrings, sphinx docs, etc -0.5.0: 2009-08-XX +0.5.0: 2009-08-06 ================= 0.5.0 was a complete refactoring to use libsidx - a C API for libspatialindex. @@ -112,8 +133,8 @@ available as a result of this refactoring. - Reraise index query errors as Python exceptions. - Improved persistence. -0.2: -================== +0.2: 19 May 2007 +================ - Link spatialindex system library. 0.1: 13 April 2007 diff --git a/MANIFEST.in b/MANIFEST.in index 16653343..983e698c 100644 --- a/MANIFEST.in +++ b/MANIFEST.in @@ -1,4 +1,4 @@ -include *.md *.txt +include *.md *.rst *.txt include MANIFEST.in recursive-include benchmarks * recursive-include tests * diff --git a/README.md b/README.md index 3c2acfd7..8abd43da 100644 --- a/README.md +++ b/README.md @@ -24,29 +24,4 @@ Wheels are available for most major platforms, and `rtree` with bundled `libspat pip install rtree ``` -# Changes - -## 1.1.0 - -* Python 3.8+ is now required (#273) -* Move project metadata to pyproject.toml (#269) -* Refactor built wheels for PyPI (#276) -* Fix memory leak when breaking mid-way in `_get_objects` and `_get_ids` (#266) (thanks @akariv!) - -## 1.0.1 - -* Fix up type hints #243 (thanks @oderby) -* Python 3.11 wheels #250 (thanks @ewouth) - -## 1.0.0 - - -* Python 3.7+ is now required (#212) (thanks @adamjstewart!) -* Type hints (#215 and others) (thanks @adamjstewart!) -* Python 3.10 wheels, including osx-arm64 #224 -* Clean up libspatialindex C API mismatches #222 (thanks @musicinmybrain!) -* Many doc updates, fixes, and type hints (thanks @adamjstewart!) #212 #221 #217 #215 -* __len__ method for index #194 -* Prevent get_coordinate_pointers from mutating inputs #205 (thanks @sjones94549!) -* linux-aarch64 wheels #183 (thanks @odidev!) -* black (#218) and flake8 (#145) linting +See [changes](https://rtree.readthedocs.io/en/latest/changes.html) for all versions. diff --git a/docs/requirements.txt b/docs/requirements.txt index ecb5cc54..49e47461 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -1 +1,2 @@ sphinx>=4 +sphinx-issues diff --git a/docs/source/changes.rst b/docs/source/changes.rst new file mode 100644 index 00000000..4bb46849 --- /dev/null +++ b/docs/source/changes.rst @@ -0,0 +1,6 @@ +.. _changes: + +Changes +.............................................................................. + +.. include:: ../../CHANGES.rst diff --git a/docs/source/class.txt b/docs/source/class.rst similarity index 100% rename from docs/source/class.txt rename to docs/source/class.rst diff --git a/docs/source/conf.py b/docs/source/conf.py index 4aa48308..4a41c041 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -1,34 +1,24 @@ +# Configuration file for the Sphinx documentation builder. # -# Rtree documentation build configuration file, created by -# sphinx-quickstart on Tue Aug 18 13:21:07 2009. -# -# This file is execfile()d with the current directory set to its containing dir. -# -# Note that not all possible configuration values are present in this -# autogenerated file. -# -# All configuration values have a default; values that are commented out -# serve to show the default. - +# For the full list of built-in configuration values, see the documentation: +# https://www.sphinx-doc.org/en/master/usage/configuration.html import sys -from typing import List sys.path.append("../../") import rtree # noqa: E402 -# If extensions (or modules to document with autodoc) are in another directory, -# add these directories to sys.path here. If the directory is relative to the -# documentation root, use os.path.abspath to make it absolute, like shown here. -# sys.path.append(os.path.abspath('.')) +# -- Project information ----------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information -# -- General configuration ----------------------------------------------- +project = "Rtree" +copyright = "2019, Sean Gilles, Howard Butler, and contributors" +author = "Sean Gilles, Howard Butler, and contributors" +version = release = rtree.__version__ -# If your documentation needs a minimal Sphinx version, state it here. -needs_sphinx = "4.0" +# -- General configuration --------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration -# Add any Sphinx extension module names here, as strings. They can be extensions -# coming with Sphinx (named 'sphinx.ext.*') or your custom ones. extensions = [ "sphinx.ext.autodoc", "sphinx.ext.doctest", @@ -36,194 +26,41 @@ "sphinx.ext.todo", "sphinx.ext.coverage", "sphinx.ext.ifconfig", + "sphinx_issues", ] -# Add any paths that contain templates here, relative to this directory. templates_path = ["_templates"] - -# The suffix of source filenames. -source_suffix = ".txt" - -# The encoding of source files. -# source_encoding = 'utf-8-sig' - -# The master toctree document. -master_doc = "index" - -# General information about the project. -project = "Rtree" -copyright = "2019, Sean Gilles, Howard Butler, and contributors." - -# The version info for the project you're documenting, acts as replacement for -# |version| and |release|, also used in various other places throughout the -# built documents. -# -# The short X.Y version. -version = rtree.__version__ -# The full version, including alpha/beta/rc tags. -release = rtree.__version__ - -# The language for content autogenerated by Sphinx. Refer to documentation -# for a list of supported languages. -# language = None - -# There are two options for replacing |today|: either, you set today to some -# non-false value, then it is used: -# today = '' -# Else, today_fmt is used as the format for a strftime call. -# today_fmt = '%B %d, %Y' - -# List of documents that shouldn't be included in the build. -# unused_docs = [] - -# List of directories, relative to source directory, that shouldn't be searched -# for source files. -exclude_trees: List[str] = [] - -# The reST default role (used for this markup: `text`) to use for all documents. -# default_role = None - -# If true, '()' will be appended to :func: etc. cross-reference text. -# add_function_parentheses = True - -# If true, the current module name will be prepended to all description -# unit titles (such as .. function::). -# add_module_names = True - -# If true, sectionauthor and moduleauthor directives will be shown in the -# output. They are ignored by default. -# show_authors = False +exclude_patterns = [] # The name of the Pygments (syntax highlighting) style to use. pygments_style = "sphinx" -# A list of ignored prefixes for module index sorting. -# modindex_common_prefix = [] - +# -- Options for HTML output ------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output -# -- Options for HTML output --------------------------------------------- -# The theme to use for HTML and HTML Help pages. Major themes that come with -# Sphinx are currently 'default' and 'sphinxdoc'. html_theme = "nature" - -# Theme options are theme-specific and customize the look and feel of a theme -# further. For a list of options available for each theme, see the -# documentation. -# html_theme_options = {} - -# Add any paths that contain custom themes here, relative to this directory. -# html_theme_path = [] - -# The name for this set of Sphinx documents. If None, it defaults to -# " v documentation". -# html_title = None - -# A shorter title for the navigation bar. Default is the same as html_title. -# html_short_title = None - -# The name of an image file (relative to this directory) to place at the top -# of the sidebar. -# html_logo = None - -# The name of an image file (within the static path) to use as favicon of the -# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 -# pixels large. -# html_favicon = None - -# 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: List[str] = [] - -# If not '', a 'Last updated on:' timestamp is inserted at every page bottom, -# using the given strftime format. -# html_last_updated_fmt = '%b %d, %Y' - -# If true, SmartyPants will be used to convert quotes and dashes to -# typographically correct entities. -# html_use_smartypants = True - -# Custom sidebar templates, maps document names to template names. -# html_sidebars = {} - -# Additional templates that should be rendered to pages, maps page names to -# template names. -# html_additional_pages = {} - -# If false, no module index is generated. -# html_use_modindex = True - -# If false, no index is generated. -# html_use_index = True - -# If true, the index is split into individual pages for each letter. -# html_split_index = False - -# If true, links to the reST sources are added to the pages. -# html_show_sourcelink = True - -# If true, "Created using Sphinx" is shown in the HTML footer. Default is True. -# html_show_sphinx = True - -# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True. -# html_show_copyright = True - -# If true, an OpenSearch description file will be output, and all pages will -# contain a tag referring to it. The value of this option must be the -# base URL from which the finished HTML is served. -# html_use_opensearch = '' - -# If nonempty, this is the file name suffix for HTML files (e.g. ".xhtml"). -# html_file_suffix = '' - -# Output file base name for HTML help builder. htmlhelp_basename = "Rtreedoc" - # -- Options for LaTeX output -------------------------------------------- -# The paper size ('letter' or 'a4'). -# latex_paper_size = 'letter' - -# The font size ('10pt', '11pt' or '12pt'). -# latex_font_size = '10pt' - # Grouping the document tree into LaTeX files. List of tuples # (source start file, target name, title, author, documentclass [howto/manual]). -latex_documents = [ - ("index", "Rtree.tex", "Rtree Documentation", "Sean Gilles", "manual") -] - -# The name of an image file (relative to this directory) to place at the top of -# the title page. -# latex_logo = None - -# For "manual" documents, if this is true, then toplevel headings are parts, -# not chapters. -# latex_use_parts = False - -# Additional stuff for the LaTeX preamble. -# latex_preamble = '' - -# Documents to append as an appendix to all manuals. -# latex_appendices = [] - -# If false, no module index is generated. -# latex_use_modindex = True +latex_documents = [("index", "Rtree.tex", "Rtree Documentation", author, "manual")] pdf_documents = [("index", "Rtree", "Rtree Documentation", "The Rtree Team")] -# A comma-separated list of custom stylesheets. Example: pdf_language = "en_US" pdf_fit_mode = "overflow" -# Example configuration for intersphinx: refer to the Python standard library. -intersphinx_mapping = {"python": ("http://docs.python.org/3", None)} - - # -- Extension configuration ------------------------------------------------- +intersphinx_mapping = {"python": ("http://docs.python.org/3", None)} + # sphinx.ext.autodoc autodoc_typehints = "description" autodoc_typehints_description_target = "documented" + +# sphinx-issues +issues_github_path = "Toblerity/rtree" +issues_commit_prefix = "" diff --git a/docs/source/history.txt b/docs/source/history.rst similarity index 100% rename from docs/source/history.txt rename to docs/source/history.rst diff --git a/docs/source/index.txt b/docs/source/index.rst similarity index 99% rename from docs/source/index.txt rename to docs/source/index.rst index 1f771ee5..725425c9 100644 --- a/docs/source/index.txt +++ b/docs/source/index.rst @@ -25,6 +25,7 @@ Documentation install tutorial class + misc changes performance history diff --git a/docs/source/install.txt b/docs/source/install.rst similarity index 100% rename from docs/source/install.txt rename to docs/source/install.rst diff --git a/docs/source/misc.rst b/docs/source/misc.rst new file mode 100644 index 00000000..d54fd1be --- /dev/null +++ b/docs/source/misc.rst @@ -0,0 +1,16 @@ +.. _misc: + +Miscellaneous Documentation +------------------------------------------------------------------------------ + +Exceptions +========== + +.. autoexception:: rtree.exceptions.RTreeError + :members: + +Finder module +============= + +.. automodule:: rtree.finder + :members: diff --git a/docs/source/performance.txt b/docs/source/performance.rst similarity index 100% rename from docs/source/performance.txt rename to docs/source/performance.rst diff --git a/docs/source/tutorial.txt b/docs/source/tutorial.rst similarity index 100% rename from docs/source/tutorial.txt rename to docs/source/tutorial.rst diff --git a/pyproject.toml b/pyproject.toml index 84873643..de6813b2 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -101,5 +101,6 @@ skip_gitignore = true color_output = true [tool.mypy] +exclude = ["docs", "build"] ignore_missing_imports = true show_error_codes = true diff --git a/rtree/finder.py b/rtree/finder.py index e03d2127..59b74e4a 100644 --- a/rtree/finder.py +++ b/rtree/finder.py @@ -1,8 +1,5 @@ """ -finder.py ------------- - -Locate `libspatialindex` shared library by any means necessary. +Locate `libspatialindex` shared library and header files. """ from __future__ import annotations