Move everything from "core" into __init__.py and rearrange docs.

Author: domdfcoding

doc-source/api/extension.rst

@@ -1,6 +1,6 @@
-===========================================
-:mod:`~seed_intersphinx_mapping.extension`
-===========================================
+==================================================================================
+:mod:`seed_intersphinx_mapping.​extension <seed_intersphinx_mapping.extension>`
+==================================================================================
 
 .. automodule:: seed_intersphinx_mapping.extension
 	:undoc-members:

doc-source/api/index.rst

@@ -0,0 +1,13 @@
+============
+Public API
+============
+
+In addition to the Sphinx extension ``seed_intersphinx_mapping`` provides a public API.
+
+.. toctree::
+	:maxdepth: 3
+	:caption: modules
+	:glob:
+
+	seed_intersphinx_mapping
+	*

doc-source/api/requirements_parsers.rst

@@ -1,6 +1,6 @@
-=====================================================
-:mod:`~seed_intersphinx_mapping.requirements_parsers`
-=====================================================
+==========================================================================================================
+:mod:`seed_intersphinx_mapping.​requirements_parsers <seed_intersphinx_mapping.requirements_parsers>`
+==========================================================================================================
 
 .. automodule:: seed_intersphinx_mapping.requirements_parsers
 	:undoc-members:

doc-source/api/core.rst renamed to doc-source/api/seed_intersphinx_mapping.rst

@@ -1,6 +1,6 @@
 =======================================
-:mod:`~seed_intersphinx_mapping.core`
+:mod:`seed_intersphinx_mapping`
 =======================================
 
-.. automodule:: seed_intersphinx_mapping.core
+.. automodule:: seed_intersphinx_mapping
 	:undoc-members:

doc-source/contributing.rst

@@ -1,5 +1,6 @@
-Overview
----------
+==============
+Contributing
+==============
 
 .. This file based on https://github.com/PyGithub/PyGithub/blob/master/CONTRIBUTING.md
 

doc-source/index.rst

@@ -158,85 +158,6 @@ This avoids having to manually compile (and keep updated) a mapping like:
 .. _core metadata: https://packaging.python.org/specifications/core-metadata
 .. _pull request: https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/about-pull-requests
 
-Installation
----------------
-
-.. start installation
-
-.. installation:: seed_intersphinx_mapping
-	:pypi:
-	:github:
-	:anaconda:
-	:conda-channels: conda-forge, domdfcoding
-
-.. end installation
-
-
-.. extensions:: seed_intersphinx_mapping
-
-Configuration
------------------
-
-.. confval:: pkg_requirements_source
-
-	The requirements source. This may be one of:
-
-	* A list of directories (relative to :confval:`repository_root`)
-	  in which to search for ``requirements.txt`` files.
-	  Any files found will be used to compile the list of requirements.
-
-	* The string ``'requirements'``.
-	  The list of requirements will be determined from the ``requirements.txt`` file
-	  in the directory given by the :confval:`repository_root` option.
-
-	* The string ``'pyproject'`` (or ``'pyproject.toml'``).
-	  The list  will be parsed from the ``[project.dependencies]`` table of the
-	  ``pyproject.toml`` file in the :confval:`repository_root`.
-
-	  .. seealso:: :pep:`621` -- Storing project metadata in pyproject.toml
-
-	* The string ``'flit'``.
-	  The list  will be parsed from the ``[tool.flit.metadata.requires]`` table of the
-	  ``pyproject.toml`` file in the :confval:`repository_root`.
-
-
-.. confval:: repository_root
-
-	The path to the repository root, relative to the Sphinx source directory.
-
-	E.g., for this repository structure:
-
-	::
-
-		.
-		├── LICENSE
-		├── README.rst
-		├── doc-source  # <- this is the Sphinx source directory
-		│   ├── index.rst
-		│   └── conf.py
-		├── requirements.txt  # <- this is the file containing the requirements
-		├── seed_intersphinx_mapping
-		│   └── __init__.py
-		├── setup.py
-		├── tests
-		└── tox.ini
-
-	the value would be ``..``, which is the default.
-
-
-Caching
---------
-
-``seed_intersphinx_mapping`` caches the documentation URLs for PyPI packages.
-The cache can be cleared as follows:
-
-.. prompt:: bash
-
-	python3 -m seed_intersphinx_mapping
-
-.. TODO:: automatic cache clearing, perhaps using ``intersphinx_cache_limit``
-
-
 Contents
 --------
 
@@ -247,15 +168,11 @@ Contents
 
 .. toctree::
 	:maxdepth: 3
-	:caption: API Reference
+	:caption: Documentation
 	:glob:
 
-	api/*
-
-.. toctree::
-	:maxdepth: 3
-	:caption: Contributing
-
+	usage
+	api/index
 	contributing
 	Source
 

doc-source/usage.rst

@@ -0,0 +1,82 @@
+=======
+Usage
+=======
+
+Installation
+---------------
+
+.. start installation
+
+.. installation:: seed_intersphinx_mapping
+	:pypi:
+	:github:
+	:anaconda:
+	:conda-channels: conda-forge, domdfcoding
+
+.. end installation
+
+
+.. extensions:: seed_intersphinx_mapping
+
+
+Configuration
+-----------------
+
+.. confval:: pkg_requirements_source
+
+	The requirements source. This may be one of:
+
+	* A list of directories (relative to :confval:`repository_root`)
+	  in which to search for ``requirements.txt`` files.
+	  Any files found will be used to compile the list of requirements.
+
+	* The string ``'requirements'``.
+	  The list of requirements will be determined from the ``requirements.txt`` file
+	  in the directory given by the :confval:`repository_root` option.
+
+	* The string ``'pyproject'`` (or ``'pyproject.toml'``).
+	  The list  will be parsed from the ``[project.dependencies]`` table of the
+	  ``pyproject.toml`` file in the :confval:`repository_root`.
+
+	  .. seealso:: :pep:`621` -- Storing project metadata in pyproject.toml
+
+	* The string ``'flit'``.
+	  The list  will be parsed from the ``[tool.flit.metadata.requires]`` table of the
+	  ``pyproject.toml`` file in the :confval:`repository_root`.
+
+
+.. confval:: repository_root
+
+	The path to the repository root, relative to the Sphinx source directory.
+
+	E.g., for this repository structure:
+
+	::
+
+		.
+		├── LICENSE
+		├── README.rst
+		├── doc-source  # <- this is the Sphinx source directory
+		│   ├── index.rst
+		│   └── conf.py
+		├── requirements.txt  # <- this is the file containing the requirements
+		├── seed_intersphinx_mapping
+		│   └── __init__.py
+		├── setup.py
+		├── tests
+		└── tox.ini
+
+	the value would be ``..``, which is the default.
+
+
+Caching
+--------
+
+``seed_intersphinx_mapping`` caches the documentation URLs for PyPI packages.
+The cache can be cleared as follows:
+
+.. prompt:: bash
+
+	python3 -m seed_intersphinx_mapping
+
+.. TODO:: automatic cache clearing, perhaps using ``intersphinx_cache_limit``

repo_helper.yml

@@ -14,6 +14,7 @@ short_desc: "Populate the Sphinx 'intersphinx_mapping' dictionary from the proje
 sphinx_html_theme: furo
 docs_fail_on_warning: true
 use_whey: true
+standalone_contrib_guide: true
 
 conda_channels:
  - conda-forge

seed_intersphinx_mapping/__init__.py

@@ -3,9 +3,13 @@
 #  __init__.py
 """
 Populate the Sphinx 'intersphinx_mapping' dictionary from the project's requirements.
+
+.. versionchanged:: 0.5.0
+
+	The functions formerly in ``seed_intersphinx_mapping.core`` can now be found here.
 """
 #
-#  Copyright © 2020 Dominic Davis-Foster <[email protected]>
+#  Copyright © 2020-2021 Dominic Davis-Foster <[email protected]>
 #
 #  Permission is hereby granted, free of charge, to any person obtaining a copy
 #  of this software and associated documentation files (the "Software"), to deal
@@ -26,14 +30,126 @@
 #  OR OTHER DEALINGS IN THE SOFTWARE.
 #
 
+# stdlib
+import functools
+import json
+from typing import Dict, Optional, Tuple, Union
+
+# 3rd party
+import requests
+from cawdrey.utils import search_dict
+from domdf_python_tools.compat import importlib_resources
+from domdf_python_tools.utils import stderr_writer
+from packaging.requirements import Requirement
+from shippinglabel import get_project_links
+
 # this package
 from seed_intersphinx_mapping.cache import cache
-from seed_intersphinx_mapping.core import get_sphinx_doc_url, seed_intersphinx_mapping
 from seed_intersphinx_mapping.extension import setup
 
 __author__: str = "Dominic Davis-Foster"
 __copyright__: str = "2020 Dominic Davis-Foster"
-
 __license__: str = "MIT License"
 __version__: str = "0.4.1"
 __email__: str = "[email protected]"
+
+__all__ = ["get_sphinx_doc_url", "fallback_mapping", "seed_intersphinx_mapping"]
+
+
+@cache
+def get_sphinx_doc_url(pypi_name: str) -> str:
+	"""
+	Returns the URL to the given project's Sphinx documentation.
+
+	Not all projects include this URL in their distributions and therefore it may not be possible to determine it from PyPI.
+
+	Responses are cached to prevent overloading the PyPI server.
+	The cache can be cleared as follows:
+
+	.. prompt:: bash
+
+		python3 -m seed_intersphinx_mapping
+
+	.. TODO:: automatic cache clearing, perhaps using ``intersphinx_cache_limit``
+
+	:param pypi_name: The name of the project on PyPI
+
+	:returns: The URL of the project's Sphinx documentation.
+
+	:raises: | :exc:`ValueError` if the url could not be determined.
+		| :exc:`packaging.requirements.InvalidRequirement` if the project could not be found on PyPI.
+
+	.. versionchanged:: 0.4.0
+
+		Now raises a :exc:`packaging.requirements.InvalidRequirement` rather than a
+		:exc:`apeye.slumber_url.exceptions.HttpNotFoundError` if the project could not be found on PyPI.
+	"""
+
+	docs_dict = search_dict(get_project_links(pypi_name), r"^[dD]oc(s|umentation)")
+
+	if docs_dict:
+
+		# Follow redirects to get actual URL
+		r = requests.head(list(docs_dict.values())[0], allow_redirects=True, timeout=10)
+		if r.status_code != 200:  # pragma: no cover
+			raise ValueError(f"Documentation URL not found: HTTP Status {r.status_code}.")
+
+		docs_url = r.url
+
+		if docs_url.endswith('/'):
+			objects_inv_url = f"{docs_url}objects.inv"
+		else:  # pragma: no cover
+			objects_inv_url = f"{docs_url}/objects.inv"
+
+		r = requests.head(objects_inv_url)
+		if r.status_code != 200:
+			raise ValueError(f"objects.inv not found at url {objects_inv_url}: HTTP Status {r.status_code}.")
+
+		return docs_url
+
+	raise ValueError("Documentation URL not found in data from PyPI.")
+
+
+@functools.lru_cache()
+def fallback_mapping() -> Dict[str, str]:
+	"""
+	Returns the fallback mapping for projects that do not provide a link to their documentation on PyPI.
+
+	The mapping is loaded from JSON data on demand, and consists of ``project_name: url`` pairs.
+	"""
+
+	return json.loads(importlib_resources.read_text("seed_intersphinx_mapping", "fallback_mapping.json"))
+
+
+def seed_intersphinx_mapping(*requirements: Union[Requirement, str]) -> Dict[str, Tuple[str, Optional[str]]]:
+	r"""
+	Returns an intersphinx mapping dictionary for the project's requirements.
+
+	:param \*requirements: The requirements to find the documentation for.
+
+	.. versionchanged:: 0.4.0
+
+		Now takes the requirements as arguments rather than
+		a directory to read the ``requirements.txt`` file from.
+	"""
+
+	intersphinx_mapping: Dict[str, Tuple[str, Optional[str]]] = {}
+
+	for requirement in requirements:
+		if isinstance(requirement, Requirement):
+			project_name = requirement.name
+		else:
+			project_name = str(requirement)
+
+		try:
+			doc_url = get_sphinx_doc_url(project_name)
+			intersphinx_mapping[project_name] = (doc_url, None)
+		except (ValueError, requests.exceptions.ConnectionError, requests.exceptions.Timeout):
+			# Couldn't get it from PyPI, trying fallback mapping
+			if project_name in fallback_mapping():
+				doc_url = fallback_mapping()[project_name]
+				intersphinx_mapping[project_name] = (doc_url, None)
+			else:
+				stderr_writer(f"WARNING: Unable to determine documentation url for project {project_name}")
+
+	return intersphinx_mapping