"Collating" all Python specific documentation

In particular, moving: - `/reference/...` -> `/python/reference/...` - `/python-binary-extension.html` -> `/python/binary-extension.html` - `/pxd/...` -> `/python/pxd/...` and updating tooling and hardcoded links to the old URIs.
dhermes · Oct 24, 2018 · 3db483b · 3db483b
1 parent e7e66ac
commit 3db483b
Show file tree

Hide file tree

Showing 31 changed files with 117 additions and 101 deletions.
diff --git a/DEVELOPMENT.rst b/DEVELOPMENT.rst
@@ -33,7 +33,7 @@ Many low-level computations have alternate implementations in Fortran.
 See the `Python Binary Extension`_ page in the documentation for a more
 detailed description.
 
-.. _Python Binary Extension: https://bezier.readthedocs.io/en/latest/python-binary-extension.html
+.. _Python Binary Extension: https://bezier.readthedocs.io/en/latest/python/binary-extension.html
 
 Building / Compiling
 ====================

diff --git a/DEVELOPMENT.rst.template b/DEVELOPMENT.rst.template
@@ -33,7 +33,7 @@ Many low-level computations have alternate implementations in Fortran.
 See the `Python Binary Extension`_ page in the documentation for a more
 detailed description.
 
-.. _Python Binary Extension: https://bezier.readthedocs.io/en/{rtd_version}/python-binary-extension.html
+.. _Python Binary Extension: https://bezier.readthedocs.io/en/{rtd_version}/python/binary-extension.html
 
 Building / Compiling
 ====================

diff --git a/README.rst b/README.rst
@@ -143,8 +143,8 @@ intersections):
 .. image:: https://raw.githubusercontent.com/dhermes/bezier/master/docs/images/curves1_and_13.png
    :align: center
 
-For API-level documentation, check out the B |eacute| zier
-`Package`_ documentation.
+For API-level documentation, check out the B |eacute| zier Python
+`package`_ documentation.
 
 Development
 -----------
@@ -159,9 +159,9 @@ License
 ``bezier`` is made available under the Apache 2.0 License. For more
 details, see `the LICENSE`_.
 
-.. _Curves: https://bezier.readthedocs.io/en/latest/reference/bezier.curve.html
-.. _Surfaces: https://bezier.readthedocs.io/en/latest/reference/bezier.surface.html
-.. _Package: https://bezier.readthedocs.io/en/latest/reference/bezier.html
+.. _Curves: https://bezier.readthedocs.io/en/latest/python/reference/bezier.curve.html
+.. _Surfaces: https://bezier.readthedocs.io/en/latest/python/reference/bezier.surface.html
+.. _package: https://bezier.readthedocs.io/en/latest/python/reference/bezier.html
 .. _DEVELOPMENT doc: https://github.com/dhermes/bezier/blob/master/DEVELOPMENT.rst
 .. _the LICENSE: https://github.com/dhermes/bezier/blob/master/LICENSE
 

diff --git a/README.rst.release.template b/README.rst.release.template
@@ -141,8 +141,8 @@ intersections):
 .. image:: https://raw.githubusercontent.com/dhermes/bezier/{version}/docs/images/curves1_and_13.png
    :align: center
 
-For API-level documentation, check out the B |eacute| zier
-`Package`_ documentation.
+For API-level documentation, check out the B |eacute| zier Python
+`package`_ documentation.
 
 Development
 -----------
@@ -157,9 +157,9 @@ License
 ``bezier`` is made available under the Apache 2.0 License. For more
 details, see `the LICENSE`_.
 
-.. _Curves: https://bezier.readthedocs.io/en/{version}/reference/bezier.curve.html
-.. _Surfaces: https://bezier.readthedocs.io/en/{version}/reference/bezier.surface.html
-.. _Package: https://bezier.readthedocs.io/en/{version}/reference/bezier.html
+.. _Curves: https://bezier.readthedocs.io/en/{version}/python/reference/bezier.curve.html
+.. _Surfaces: https://bezier.readthedocs.io/en/{version}/python/reference/bezier.surface.html
+.. _package: https://bezier.readthedocs.io/en/{version}/python/reference/bezier.html
 .. _DEVELOPMENT doc: https://github.com/dhermes/bezier/blob/{version}/DEVELOPMENT.rst
 .. _the LICENSE: https://github.com/dhermes/bezier/blob/{version}/LICENSE
 

diff --git a/README.rst.template b/README.rst.template
@@ -136,8 +136,8 @@ intersections):
 {testcleanup}.. image:: {img_prefix}images/curves1_and_13.png
    :align: center
 
-For API-level documentation, check out the B |eacute| zier
-:doc:`Package <reference/bezier>` documentation.
+For API-level documentation, check out the B |eacute| zier Python
+:doc:`package <python/reference/bezier>` documentation.
 
 Development
 -----------

diff --git a/docs/abi/index.rst b/docs/abi/index.rst
@@ -31,6 +31,6 @@ Installation
 Currently (as of October 19, 2018) there is no direct support for building
 ``libbezier`` or for installing the header files.
 
-However, the :doc:`../python-binary-extension` document explains how to locate
+However, the :doc:`../python/binary-extension` document explains how to locate
 a built ``libbezier`` static library and the C headers once the ``bezier``
 Python package has been installed.
diff --git a/docs/index.rst b/docs/index.rst
@@ -16,12 +16,10 @@
    :hidden:
    :maxdepth: 4
 
-   Python Package <reference/bezier>
+   python/index
    abi/index
-   pxd/index
    curve-curve-intersection
    algorithm-helpers
-   python-binary-extension
    development
    releases/index
 
@@ -203,8 +201,8 @@ intersections):
 .. image:: images/curves1_and_13.png
    :align: center
 
-For API-level documentation, check out the B |eacute| zier
-:doc:`Package <reference/bezier>` documentation.
+For API-level documentation, check out the B |eacute| zier Python
+:doc:`package <python/reference/bezier>` documentation.
 
 Development
 -----------

diff --git a/docs/index.rst.release.template b/docs/index.rst.release.template
@@ -14,12 +14,10 @@
    :hidden:
    :maxdepth: 4
 
-   Python Package <reference/bezier>
+   python/index
    abi/index
-   pxd/index
    curve-curve-intersection
    algorithm-helpers
-   python-binary-extension
    development
    releases/index
 
@@ -201,8 +199,8 @@ intersections):
 .. image:: images/curves1_and_13.png
    :align: center
 
-For API-level documentation, check out the B |eacute| zier
-:doc:`Package <reference/bezier>` documentation.
+For API-level documentation, check out the B |eacute| zier Python
+:doc:`package <python/reference/bezier>` documentation.
 
 Development
 -----------

diff --git a/docs/python-binary-extension.rst → docs/python/binary-extension.rst b/docs/python-binary-extension.rst → docs/python/binary-extension.rst
@@ -1,6 +1,6 @@
-#######################
-Python Binary Extension
-#######################
+################
+Binary Extension
+################
 
 .. note::
 
@@ -14,7 +14,7 @@ Python Binary Extension
    .. _file an issue: https://github.com/dhermes/bezier/issues/new
 
 The ``bezier`` Python package has optional speedups that wrap the
-``libbezier`` :doc:`library <abi/index>`. These are incorporated into the
+``libbezier`` :doc:`library <../abi/index>`. These are incorporated into the
 Python interface via `Cython`_ as a binary extension.
 
 .. _Cython: https://cython.readthedocs.io/

diff --git a/docs/python-binary-extension.rst.template → docs/python/binary-extension.rst.template b/docs/python-binary-extension.rst.template → docs/python/binary-extension.rst.template
@@ -1,6 +1,6 @@
-#######################
-Python Binary Extension
-#######################
+################
+Binary Extension
+################
 
 .. note::
 
@@ -14,7 +14,7 @@ Python Binary Extension
    .. _file an issue: https://github.com/dhermes/bezier/issues/new
 
 The ``bezier`` Python package has optional speedups that wrap the
-``libbezier`` :doc:`library <abi/index>`. These are incorporated into the
+``libbezier`` :doc:`library <../abi/index>`. These are incorporated into the
 Python interface via `Cython`_ as a binary extension.
 
 .. _Cython: https://cython.readthedocs.io/

diff --git a/docs/python/index.rst b/docs/python/index.rst
@@ -0,0 +1,18 @@
+Python Package
+==============
+
+Documentation for the ``bezier`` Python :doc:`package <reference/bezier>` is
+provided here. In addition to the Python package, :doc:`pxd/index` are
+provided for downstream packages which seek to use ``libbezier`` from Cython
+in the same way the ``bezier`` package does.
+
+For more information on how the :doc:`binary-extension` is built, a
+document is provided with explanations on the headers, compilation process,
+build relocatable wheels and other topics.
+
+.. toctree::
+   :hidden:
+
+   reference/bezier
+   binary-extension
+   pxd/index
diff --git a/docs/pxd/curve.rst → docs/python/pxd/curve.rst b/docs/pxd/curve.rst → docs/python/pxd/curve.rst
@@ -2,5 +2,5 @@
 ``bezier._curve``
 #################
 
-.. literalinclude:: ../../src/bezier/_curve.pxd
+.. literalinclude:: ../../../src/bezier/_curve.pxd
    :language: cython
diff --git a/docs/pxd/curve_intersection.rst → docs/python/pxd/curve_intersection.rst b/docs/pxd/curve_intersection.rst → docs/python/pxd/curve_intersection.rst
@@ -2,5 +2,5 @@
 ``bezier._curve_intersection``
 ##############################
 
-.. literalinclude:: ../../src/bezier/_curve_intersection.pxd
+.. literalinclude:: ../../../src/bezier/_curve_intersection.pxd
    :language: cython
diff --git a/docs/pxd/helpers.rst → docs/python/pxd/helpers.rst b/docs/pxd/helpers.rst → docs/python/pxd/helpers.rst
@@ -2,5 +2,5 @@
 ``bezier._helpers``
 ###################
 
-.. literalinclude:: ../../src/bezier/_helpers.pxd
+.. literalinclude:: ../../../src/bezier/_helpers.pxd
    :language: cython
diff --git a/docs/pxd/index.rst → docs/python/pxd/index.rst b/docs/pxd/index.rst → docs/python/pxd/index.rst
@@ -89,9 +89,9 @@ in ``bezier/curve.h``.
 .. toctree::
    :titlesonly:
 
-   curve
-   curve_intersection
-   helpers
-   status
-   surface
-   surface_intersection
+   curve <curve>
+   curve_intersection <curve_intersection>
+   helpers <helpers>
+   status <status>
+   surface <surface>
+   surface_intersection <surface_intersection>
diff --git a/docs/pxd/status.rst → docs/python/pxd/status.rst b/docs/pxd/status.rst → docs/python/pxd/status.rst
@@ -2,5 +2,5 @@
 ``bezier._status``
 ##################
 
-.. literalinclude:: ../../src/bezier/_status.pxd
+.. literalinclude:: ../../../src/bezier/_status.pxd
    :language: cython
diff --git a/docs/pxd/surface.rst → docs/python/pxd/surface.rst b/docs/pxd/surface.rst → docs/python/pxd/surface.rst
@@ -2,5 +2,5 @@
 ``bezier._surface``
 ###################
 
-.. literalinclude:: ../../src/bezier/_surface.pxd
+.. literalinclude:: ../../../src/bezier/_surface.pxd
    :language: cython
diff --git a/docs/pxd/surface_intersection.rst → docs/python/pxd/surface_intersection.rst b/docs/pxd/surface_intersection.rst → docs/python/pxd/surface_intersection.rst
@@ -2,5 +2,5 @@
 ``bezier._surface_intersection``
 ################################
 
-.. literalinclude:: ../../src/bezier/_surface_intersection.pxd
+.. literalinclude:: ../../../src/bezier/_surface_intersection.pxd
    :language: cython
diff --git a/docs/reference/bezier.curve.rst → docs/python/reference/bezier.curve.rst b/docs/reference/bezier.curve.rst → docs/python/reference/bezier.curve.rst
diff --git a/docs/reference/bezier.curved_polygon.rst → ...ython/reference/bezier.curved_polygon.rst b/docs/reference/bezier.curved_polygon.rst → ...ython/reference/bezier.curved_polygon.rst
diff --git a/docs/reference/bezier.rst → docs/python/reference/bezier.rst b/docs/reference/bezier.rst → docs/python/reference/bezier.rst
diff --git a/docs/reference/bezier.surface.rst → docs/python/reference/bezier.surface.rst b/docs/reference/bezier.surface.rst → docs/python/reference/bezier.surface.rst
diff --git a/docs/releases/latest.rst b/docs/releases/latest.rst
@@ -31,7 +31,7 @@ Documentation
    In the process, changed most references to the "native" Python extension to
    instead call it a "binary" extension.
 -  Added a "Cython ``.pxd``
-   `Declarations <http://bezier.readthedocs.io/en/0.8.1.dev1/pxd/index.html>`__"
+   `Declarations <http://bezier.readthedocs.io/en/0.8.1.dev1/python/pxd/index.html>`__"
    document
    (`f99db20 <https://github.com/dhermes/bezier/commit/f99db20312bb4ba7e5943195020a8ced4be9457b>`__).
    Fixed `#122 <https://github.com/dhermes/bezier/issues/122>`__.
@@ -66,9 +66,9 @@ New Features
 ~~~~~~~~~~~~
 
 -  Added implementation for ``Surface.area``
-   `property <http://bezier.readthedocs.io/en/0.8.1/reference/bezier.surface.html#bezier.surface.Surface.area>`__
+   `property <http://bezier.readthedocs.io/en/0.8.1/python/reference/bezier.surface.html#bezier.surface.Surface.area>`__
    and ``CurvedPolygon.area``
-   `property <http://bezier.readthedocs.io/en/0.8.1/reference/bezier.curved_polygon.html#bezier.curved_polygon.CurvedPolygon.area>`__
+   `property <http://bezier.readthedocs.io/en/0.8.1/python/reference/bezier.curved_polygon.html#bezier.curved_polygon.CurvedPolygon.area>`__
    (`eb6077e <https://github.com/dhermes/bezier/commit/eb6077eab4f6ca0d72de6194f1789a2d0eada8b0>`__).
 
 Non-Public API
@@ -81,11 +81,11 @@ Non-Public API
    -  ``bezier._geometric_intersection.set_max_candidates()``
    -  ``bezier._geometric_intersection.get_max_candidates()``
 -  Removing cached values for ``Curve.length``
-   `property <http://bezier.readthedocs.io/en/0.8.1/reference/bezier.curve.html#bezier.curve.Curve.length>`__,
+   `property <http://bezier.readthedocs.io/en/0.8.1/python/reference/bezier.curve.html#bezier.curve.Curve.length>`__,
    ``Surface.area``
-   `property <http://bezier.readthedocs.io/en/0.8.1/reference/bezier.surface.html#bezier.surface.Surface.area>`__
+   `property <http://bezier.readthedocs.io/en/0.8.1/python/reference/bezier.surface.html#bezier.surface.Surface.area>`__
    and ``Surface.is_valid``
-   `property <http://bezier.readthedocs.io/en/0.8.1/reference/bezier.surface.html#bezier.surface.Surface.is_valid>`__
+   `property <http://bezier.readthedocs.io/en/0.8.1/python/reference/bezier.surface.html#bezier.surface.Surface.is_valid>`__
    (`34d48d6 <https://github.com/dhermes/bezier/commit/34d48d6900963734d7fb82f13bd3f37416cc6efe>`__).
 
 Build

diff --git a/scripts/build_docs.sh b/scripts/build_docs.sh
@@ -16,16 +16,16 @@
 
 set -e
 
-rm -r docs/reference
+rm -r docs/python/reference
 OPTIONS="members,inherited-members,undoc-members,show-inheritance"
 SPHINX_APIDOC_OPTIONS="${OPTIONS}" sphinx-apidoc \
     --separate \
     --force \
     --module-first \
-    --output-dir docs/reference \
+    --output-dir docs/python/reference \
     src/bezier
 # Remove unused modules.rst
-rm docs/reference/modules.rst
+rm docs/python/reference/modules.rst
 # Rewrite main package RST
 python scripts/rewrite_package_rst.py
 

diff --git a/scripts/check_doc_templates.py b/scripts/check_doc_templates.py
@@ -9,6 +9,7 @@
 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 # See the License for the specific language governing permissions and
 # limitations under the License.
+
 """Check that the current ``README.rst`` is built from the template.
 
 Also checks a collection of other documents:
@@ -40,10 +41,10 @@
 DEVELOPMENT_TEMPLATE = os.path.join(_ROOT_DIR, "DEVELOPMENT.rst.template")
 DEVELOPMENT_FILE = os.path.join(_ROOT_DIR, "DEVELOPMENT.rst")
 BINARY_EXT_FILE = os.path.join(
-    _ROOT_DIR, "docs", "python-binary-extension.rst"
+    _ROOT_DIR, "docs", "python", "binary-extension.rst"
 )
 BINARY_EXT_TEMPLATE = os.path.join(
-    _ROOT_DIR, "docs", "python-binary-extension.rst.template"
+    _ROOT_DIR, "docs", "python", "binary-extension.rst.template"
 )
 RTD_VERSION = "latest"
 REVISION = "master"
@@ -106,12 +107,10 @@
    :hidden:
    :maxdepth: 4
 
-   Python Package <reference/bezier>
+   python/index
    abi/index
-   pxd/index
    curve-curve-intersection
    algorithm-helpers
-   python-binary-extension
    development
    releases/index
 
@@ -120,9 +119,9 @@
     "https://raw.githubusercontent.com/dhermes/bezier/{revision}/docs/"
 )
 EXTRA_LINKS = """\
-.. _Curves: https://bezier.readthedocs.io/en/{rtd_version}/reference/bezier.curve.html
-.. _Surfaces: https://bezier.readthedocs.io/en/{rtd_version}/reference/bezier.surface.html
-.. _Package: https://bezier.readthedocs.io/en/{rtd_version}/reference/bezier.html
+.. _Curves: https://bezier.readthedocs.io/en/{rtd_version}/python/reference/bezier.curve.html
+.. _Surfaces: https://bezier.readthedocs.io/en/{rtd_version}/python/reference/bezier.surface.html
+.. _package: https://bezier.readthedocs.io/en/{rtd_version}/python/reference/bezier.html
 .. _DEVELOPMENT doc: https://github.com/dhermes/bezier/blob/{revision}/DEVELOPMENT.rst
 """
 BERNSTEIN_BASIS_SPHINX = """\
@@ -336,7 +335,7 @@ def populate_readme(revision, rtd_version, **extra_kwargs):
     sphinx_docs = []
     to_replace = functools.partial(doc_replace, sphinx_docs=sphinx_docs)
     readme_contents = DOC_EXPR.sub(to_replace, readme_contents)
-    if sphinx_docs != ["reference/bezier", "development"]:
+    if sphinx_docs != ["python/reference/bezier", "development"]:
         raise ValueError("Unexpected sphinx_docs", sphinx_docs)
 
     return readme_contents
@@ -559,10 +558,10 @@ def development_verify():
 
 
 def native_libraries_verify():
-    """Populate the template and compare to ``docs/python-binary-extension.rst``.
+    """Populate the template and compare to ``binary-extension.rst``.
 
     Raises:
-        ValueError: If the current ``docs/python-binary-extension.rst`` doesn't
+        ValueError: If the current ``docs/python/binary-extension.rst`` doesn't
             agree with the expected value computed from the template.
     """
     with open(BINARY_EXT_TEMPLATE, "r") as file_obj:
@@ -574,13 +573,13 @@ def native_libraries_verify():
         err_msg = "\n" + get_diff(
             contents,
             expected,
-            "docs/python-binary-extension.rst.actual",
-            "docs/python-binary-extension.rst.expected",
+            "docs/python/binary-extension.rst.actual",
+            "docs/python/binary-extension.rst.expected",
         )
         raise ValueError(err_msg)
 
     else:
-        print("docs/python-binary-extension.rst contents are as expected.")
+        print("docs/python/binary-extension.rst contents are as expected.")
 
 
 def main():