DOC: Get docs somewhat in shape.

Author: DWesl

CHANGELOG.rst

@@ -5,6 +5,5 @@ Changelog
 Version 0.1
 ===========
 
-- Feature A added
-- FIX: nasty bug #1729 fixed
-- add your changes here!
+- Pulled the ``check_python_h_first.py`` script from SciPy into its
+  own package

CONTRIBUTING.rst

@@ -27,7 +27,7 @@
 Contributing
 ============
 
-Welcome to ``check-python-h-first`` contributor's guide.
+Welcome to the ``check-python-h-first`` contributor's guide.
 
 This document focuses on getting any potential contributor familiarized
 with the development processes, but `other kinds of contributions`_ are also
@@ -106,11 +106,16 @@ and use Python's built-in web server for a preview in your web browser
 Code Contributions
 ==================
 
-.. todo:: Please include a reference or explanation about the internals of the project.
-
-   An architecture description, design principles or at least a summary of the
-   main concepts will make it easy for potential contributors to get started
-   quickly.
+- ``src/check_python_h_first/single_file.py`` contains the checks for
+  a single file
+- ``src/check_python_h_first/wrapper.py`` contains functions to sort a
+  list of files, send the result to the functions in
+  ``single_file.py``, and aggregate the results.
+- ``src/check_python_h_first/get_submodule_paths.py`` contains checks
+  for files managed by different repositories.
+- ``src/check_python_h_first/__main__.py`` provides a command-line
+  interface.
+- The docs are under ``docs``
 
 Submit an issue
 ---------------
@@ -151,7 +156,6 @@ Clone the repository
 
    to be able to import the package under development in the Python REPL.
 
-   .. todo:: if you are not using pre-commit, please remove the following item:
 
 #. Install |pre-commit|_::
 
@@ -182,8 +186,6 @@ Implement your changes
 
    to record your changes in git_.
 
-   .. todo:: if you are not using pre-commit, please remove the following item:
-
    Please make sure to see the validation messages from |pre-commit|_ and fix
    any eventual issues.
    This should automatically use flake8_/black_ to check/fix the code style
@@ -218,11 +220,10 @@ Submit your contribution
 #. Go to the web page of your fork and click |contribute button|
    to send your changes for review.
 
-   .. todo:: if you are using GitHub, you can uncomment the following paragraph
-
-      Find more detailed information in `creating a PR`_. You might also want to open
-      the PR as a draft first and mark it as ready for review after the feedbacks
-      from the continuous integration (CI) system or any required fixes.
+   Find more detailed information in `creating a PR`_. You might also
+   want to open the PR as a draft first and mark it as ready for
+   review after the feedbacks from the continuous integration (CI)
+   system or any required fixes.
 
 
 Troubleshooting
@@ -302,7 +303,7 @@ on PyPI_, the following steps can be used to release a new version for
 
 
 
-.. [#contrib1] Even though, these resources focus on open source projects and
+.. [#contrib1] Even though these resources focus on open source projects and
    communities, the general ideas behind collaborating with other developers
    to collectively create software are general and can be applied to all sorts
    of environments, including private companies and proprietary code bases.
@@ -314,8 +315,8 @@ on PyPI_, the following steps can be used to release a new version for
 .. |the repository service| replace:: GitHub
 .. |contribute button| replace:: "Create pull request"
 
-.. _repository: https://github.com/<USERNAME>/check-python-h-first
-.. _issue tracker: https://github.com/<USERNAME>/check-python-h-first/issues
+.. _repository: https://github.com/DWesl/check-python-h-first
+.. _issue tracker: https://github.com/DWesl/check-python-h-first/issues
 .. <-- end -->
 
 

README.rst

@@ -12,10 +12,14 @@ check-python-h-first
 ====================
 
 
-Script to check whether Python.h is included first in any headers or
+Package to check whether Python.h is included first in any headers or
 source files.
+Python advises extension modules include ``Python.h`` `before other
+files
+<https://docs.python.org/3/extending/extending.html#a-simple-example>`_.
+This package checks that source files conform to that suggestion.
 
-This file does not handle mazes of ``#ifdef``s: it checks each file
+This file does not handle mazes of ``#ifdef``: it checks each file
 for ``#include``, whether the file included is ``Python.h``, and, if
 so, whether that's the first ``#include`` in that file.
 

docs/index.rst

@@ -2,9 +2,18 @@
 check-python-h-first
 ====================
 
-This is the documentation of **check-python-h-first**.
+Python advises extension modules include ``Python.h`` `before other
+files
+<https://docs.python.org/3/extending/extending.html#a-simple-example>`_.
+This package checks that source files conform to that suggestion.
 
-.. note::
+The intended use is ``check_python_h_first path/to/header.h
+path/to/source.c``: the script will tell you if the files on the
+command line include other headers before ``Python.h``.  It will also
+allow certain headers from Pybind or NumPy as the first included
+header.
+
+.. comment
 
     This is the main page of your project's `Sphinx`_ documentation.
     It is formatted in `reStructuredText`_. Add additional pages

src/check_python_h_first/get_submodule_paths.py

@@ -1,6 +1,9 @@
 """Find files in submodules.
 
 Those should be fixed in upstream project repos, not here.
+
+Originally implemented `in SciPy
+<https://github.com/scipy/scipy/blob/888ca356e/tools/get_submodule_paths.py>`_
 """
 
 import glob

src/check_python_h_first/single_file.py

@@ -1,6 +1,9 @@
 """Check that Python.h is included before any stdlib headers.
 
 May be a bit overzealous, but it should get the job done.
+
+Originally implemented `in SciPy
+<https://github.com/scipy/scipy/blob/888ca356/tools/check_python_h_first.py>`_
 """
 
 import os.path

src/check_python_h_first/wrapper.py

@@ -5,6 +5,8 @@
 :func:`.single_file.check_python_h_included_first` on each file,
 collating the results.
 
+Originally implemented `in SciPy
+<https://github.com/scipy/scipy/blob/888ca356/tools/check_python_h_first.py>`_
 """
 
 import fnmatch