doc: minor doc improvements

Signed-off-by: Paul Horton <[email protected]>

docs/changelog.rst

@@ -1,8 +1,15 @@
-Changelog
-=========
+.. # Licensed under the Apache License, Version 2.0 (the "License");
+   # you may not use this file except in compliance with the License.
+   # You may obtain a copy of the License at
+   #
+   #     http://www.apache.org/licenses/LICENSE-2.0
+   #
+   # Unless required by applicable law or agreed to in writing, software
+   # distributed under the License is distributed on an "AS IS" BASIS,
+   # 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.
+   #
+   # SPDX-License-Identifier: Apache-2.0
 
-The `changelog` for `requirements-parser` is now published on GitHub.
-
-See the Changelog_ on GitHub.
-
-.. _Changelog: https://github.com/madpah/requirements-parser/blob/master/CHANGELOG.md
+.. mdinclude:: ../CHANGELOG.md

docs/conf.py

@@ -1,5 +1,21 @@
-#!/usr/bin/env python3
-# -*- coding: utf-8 -*-
+# encoding: utf-8
+
+# This file is part of requirements-parser library.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# 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.
+#
+# SPDX-License-Identifier: Apache-2.0
+
 #
 # Requirements Parser documentation build configuration file, created by
 # sphinx-quickstart on Fri Aug 16 07:44:12 2013.
@@ -24,7 +40,6 @@
 
 master_doc = 'index'
 
-
 # -- General configuration ---------------------------------------------------
 
 # Add any Sphinx extension module names here, as strings. They can be
@@ -33,31 +48,30 @@
 extensions = [
     "sphinx.ext.autodoc",
     "sphinx.ext.viewcode",
-    # "sphinx.ext.napoleon",
-    # "sphinx.ext.intersphinx",
-    # "sphinx.ext.autosectionlabel",
-    # "sphinx_copybutton",
+    "sphinx_rtd_theme",
+    "m2r2"
 ]
 
+# Support both RST and MD
+source_suffix = ['.rst', '.md']
+
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ["_templates"]
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
 # This pattern also affects html_static_path and html_extra_path.
-exclude_patterns = ['_build']
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
 
 
 # -- Options for HTML output -------------------------------------------------
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #
-# html_theme = "alabaster"
+html_theme = 'sphinx_rtd_theme'
 
 # 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 = ["_static"]
-
-intersphinx_mapping = {"python": ("http://docs.python.org/3", None)}
+html_static_path = ["_static"]

docs/index.rst

@@ -1,34 +1,49 @@
+.. # Licensed under the Apache License, Version 2.0 (the "License");
+   # you may not use this file except in compliance with the License.
+   # You may obtain a copy of the License at
+   #
+   #     http://www.apache.org/licenses/LICENSE-2.0
+   #
+   # Unless required by applicable law or agreed to in writing, software
+   # distributed under the License is distributed on an "AS IS" BASIS,
+   # 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.
+   #
+   # SPDX-License-Identifier: Apache-2.0
+
 Welcome to Requirements Parser's documentation!
 ===============================================
 
-
 Requirements parser is a Python module for parsing Pip_ requirement files.
 
-
 .. _Pip: http://www.pip-installer.org
 
-
 Requirements parser is (now) `Apache 2.0`_ licensed.
 
 .. _Apache 2.0: https://www.apache.org/licenses/LICENSE-2.0
 
-
 Quickstart:
 
-::
+.. code-block:: python
+
+    import requirements
 
-    >>> import requirements
-    >>> reqfile = """
+    reqfile = """
     Django>=1.5,<1.6
     DocParser[PDF]==1.0.0
     """
-    >>> for req in requirements.parse(reqfile):
-    ...     print(req.name, req.specs, req.extras)
-    ...
+
+    for req in requirements.parse(reqfile):
+        print(req.name, req.specs, req.extras)
+
+Will output:
+
+::
+
     Django [('>=', '1.5'), ('<', '1.6')] []
     DocParser [('==', '1.0.0')] ['pdf']
 
-
 Contents:
 
 .. toctree::

docs/lowlevel.rst

@@ -1,21 +1,34 @@
+.. # Licensed under the Apache License, Version 2.0 (the "License");
+   # you may not use this file except in compliance with the License.
+   # You may obtain a copy of the License at
+   #
+   #     http://www.apache.org/licenses/LICENSE-2.0
+   #
+   # Unless required by applicable law or agreed to in writing, software
+   # distributed under the License is distributed on an "AS IS" BASIS,
+   # 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.
+   #
+   # SPDX-License-Identifier: Apache-2.0
+
 Low level API
 =============
 
-Higher level parsing
+Higher Level Parsing
 --------------------
 
 Typically this is called via:
 
-::
+.. code-block:: python
 
-     >>> import requirements
-     >>> requirements.parse('django>=1.5')
+     import requirements
+     requirements.parse('django>=1.5')
 
 .. automodule:: requirements.parser
     :members:
 
-
-Lower level parsing
+Lower Level Parsing
 -------------------
 
 Under the hood, the :class:`Requirement <requirements.requirement.Requirement>`
@@ -25,7 +38,7 @@ class does most of the heavy lifting.
     :members:
 
 
-Misc functions
+Misc Functions
 --------------
 
 .. automodule:: requirements

docs/requirements.txt

@@ -0,0 +1,24 @@
+# encoding: utf-8
+
+# This file is part of requirements-parser library.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# 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.
+#
+# SPDX-License-Identifier: Apache-2.0
+
+# This file includes dependencies specifically required to build our Documentation.
+
+m2r2>=0.3.2
+Sphinx>=4.3.2
+sphinx-autoapi>=1.8.4
+sphinx-rtd-theme>=1.0.0

docs/usage.rst

@@ -1,19 +1,30 @@
+.. # Licensed under the Apache License, Version 2.0 (the "License");
+   # you may not use this file except in compliance with the License.
+   # You may obtain a copy of the License at
+   #
+   #     http://www.apache.org/licenses/LICENSE-2.0
+   #
+   # Unless required by applicable law or agreed to in writing, software
+   # distributed under the License is distributed on an "AS IS" BASIS,
+   # 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.
+   #
+   # SPDX-License-Identifier: Apache-2.0
+
 Usage
 =====
 
-Requirements parser works very similarly to the way pip actually parses
-requirement files except that pip typically proceeds to install the
-relevant packages.
-
-Requirements come in a variety of forms such as requirement specifiers
-(such as requirements>=0.0.5), version control URIs, other URIs and local
-file paths.
+Requirements parser works very similarly to the way pip actually parses requirement files except that pip typically
+proceeds to install the relevant packages.
 
+Requirements come in a variety of forms such as requirement specifiers (such as requirements>=0.0.5), version control
+URIs, other URIs and local file paths.
 
 Parsing requirement specifiers
 ------------------------------
 
-::
+.. code-block:: python
 
     import requirements
     req = "django>=1.5,<1.6"
@@ -22,11 +33,10 @@ Parsing requirement specifiers
     parsed.specs      # [('>=', '1.5'), ('<', '1.6')]
     parsed.specifier  # True
 
-
 Parsing version control requirements
 ------------------------------------
 
-::
+.. code-block:: python
 
     req = "-e git+git://github.com/toastdriven/django-haystack@259274e4127f723d76b893c87a82777f9490b960#egg=django_haystack"
     parsed = list(requirements.parse(req))[0]
@@ -40,7 +50,7 @@ Parsing version control requirements
 Parsing local files
 -------------------
 
-::
+.. code-block:: python
 
     req = "-e path/to/project"
     parsed = list(requirements.parse(req))[0]