Merge pull request #1 from davidpeckham/mkdocs

Added MkDocs documentation
davidpeckham · Feb 3, 2024 · 95b8baf · 95b8baf
2 parents fade7ad + aa1e804
commit 95b8baf
Show file tree

Hide file tree

Showing 21 changed files with 402 additions and 259 deletions.
diff --git a/.gitignore b/.gitignore
@@ -161,3 +161,4 @@ cython_debug/
 #  option (not recommended) you can uncomment the following to ignore the entire idea folder.
 #.idea/
 vin/.DS_Store
+docs/changelog.md
diff --git a/.linkcheckerrc b/.linkcheckerrc
@@ -0,0 +1,5 @@
+# https://linkchecker.github.io/linkchecker/man/linkcheckerrc.html
+[filtering]
+ignore=
+
+[AnchorCheck]
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -0,0 +1,20 @@
+# Changelog
+
+## v0.2.0 (2024-02-03)
+
+[GitHub release](https://github.com/davidpeckham/vin/releases/tag/v0.2.0)
+
+### New Features
+
+* Validate VIN length, characters, and check digit, with the option to correct the check digit.
+* Decode the manufacturer and model year from a VIN
+* Documentation
+
+### Fixes
+
+* Updated annotations for `VIN.vds` and `VIN.vis` to show that they don't return None
+* Annotated `VIN.model_year` to show that it returns int, and removed the else condition that allowed it to return None
+* Inlined `VIN.is_vin_character` in the default constructor
+* Converted property `VIN.check_digit` to class method  `VIN.calculate_check_digit`
+* Converted ``constants.VIN_CHARACTERS`` from list to string
+* Renamed GitHub workflows as .yml (from .yaml)
diff --git a/CHANGELOG.rst b/CHANGELOG.rst
diff --git a/README.md b/README.md
@@ -2,23 +2,80 @@
 
 [![PyPI - Version](https://img.shields.io/pypi/v/vin.svg)](https://pypi.org/project/vin)
 [![PyPI - Python Version](https://img.shields.io/pypi/pyversions/vin.svg)](https://pypi.org/project/vin)
+[![license](https://img.shields.io/github/license/davidpeckham/vin.svg)](https://github.com/davidpeckham/vin/blob/main/LICENSE)
+
 
 -----
 
-**Table of Contents**
+**Contents**
 
+- [Why use VIN?](#why-use-vin)
+- [Vehicle Identification Number](#vehicle-identification-number)
+- [Vehicle Data](#vehicle-data)
 - [Installation](#installation)
 - [License](#license)
 
-## Installation
+VIN validates Vehicle Identification Numbers and decodes the vehicle's manufacturer, make, model, and model year.
 
-```console
-pip install vin
-```
+    >>> from vin import VIN
 
-## License
+    >>> vin("5FNYF5H59HB011946").manufacturer
+    Honda
+
+    >>> vin("YT9NN1U14KA007175").manufacturer
+    Koenigsegg
+
+    >>> vin("5FNYF5H59HB011946").model_year
+    2017
+
+## Why use VIN?
+
+- **Accurate** &mdash; Vehicle information is provided by the National Highway Traffic Safety Administration.
+- **Fast** &mdash; Vehicle data is included and periodically updated, so validation and decoding are fast.
+
+## Vehicle Identification Number
+
+A ``VIN`` is a unique 17-character Vehicle Identification Number.
+
+* Assigned by vehicle manufacturers
+* Uniquely identifies vehicles manufactured for sale or use in the United States since 1980
+* Governed by the U.S. National Highway Traffic Safety Administration (NHTSA)
+
+The structure of the VIN is:
 
-`vin` is distributed under the terms of the [MIT](https://spdx.org/licenses/MIT.html) license.
+                                      model year
+                                          |
+                 WMI          check digit | plant
+               |-----|                 |  |  |  |--- serial ----|
+    Position   1  2  3  4  5  6  7  8  9  10 11 12 13 14 15 16 17
+                        |-----------|     |---------------------|
+                             VDS                    VIS
 
+The World Manufacturer Identifier (WMI) holds the country, region, and
+name of the vehicle manufacturer. Mass-market manufacturers are assigned
+a three-character WMI. Specialized manufacturers are assigned a six-
+character WMI (positions 1-3 and 12-14)
+
+The Vehicle Description Section (VDS) is defined by manufacturers to
+identify the vehicle make, model, body type, engine type, restraints,
+and the weight class (for trucks and multi-purpose vehicles).
+
+The Vehicle Identification Section (VIS) identifies the model year,
+plant where the vehicle was made, and the vehicle's serial number.
+
+For more information, see the [VIN specification](https://www.ecfr.gov/current/title-49/subtitle-B/chapter-V/part-565).
+
+Installation
+------------
+
+Use ``pip`` to install the library:
+
+    $ pip install vin
+
+## Vehicle Data
+
+Vehicle data is provided by the U.S. National Highway Traffic Safety Administration (NHTSA) [Product Information Catalog and Vehicle Listing (vPIC)](https://vpic.nhtsa.dot.gov).
+
+## License
 
-More
+`VIN` is distributed under the terms of the [MIT](https://spdx.org/licenses/MIT.html) license.
diff --git a/docs/Makefile b/docs/Makefile
diff --git a/docs/api.md b/docs/api.md
@@ -0,0 +1,6 @@
+# API
+
+::: vin.VIN
+    options:
+        members_order: source
+        filters: ['!_vin', '!__repr__', '!__str__']
diff --git a/docs/help.md b/docs/help.md
@@ -0,0 +1,9 @@
+# Help
+
+## :material-api: API Documentation
+
+The [API documentation](api.md) is the best way to learn what VIN can do for you.
+
+## :simple-github: GitHub Issues
+
+Use [GitHub issues](https://github.com/davidpeckham/vin/issues) to ask questions, report issues, and suggest changes.
diff --git a/docs/hooks.py b/docs/hooks.py
@@ -0,0 +1,5 @@
+import shutil
+
+
+def copy_history(*args, **kwargs):
+    shutil.copy("CHANGELOG.md", "docs/changelog.md")
diff --git a/docs/index.md b/docs/index.md
@@ -0,0 +1,74 @@
+# VIN
+
+[![PyPI - Version](https://img.shields.io/pypi/v/vin.svg)](https://pypi.org/project/vin)
+[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/vin.svg)](https://pypi.org/project/vin)
+[![license](https://img.shields.io/github/license/davidpeckham/vin.svg)](https://github.com/davidpeckham/vin/blob/main/LICENSE)
+
+
+-----
+
+VIN validates Vehicle Identification Numbers and decodes the vehicle's manufacturer, make, model, and model year.
+
+    >>> from vin import VIN
+
+    >>> vin("5FNYF5H59HB011946").manufacturer
+    Honda
+
+    >>> vin("YT9NN1U14KA007175").manufacturer
+    Koenigsegg
+
+    >>> vin("5FNYF5H59HB011946").model_year
+    2017
+
+## Why use VIN?
+
+- **Accurate** &mdash; Vehicle information is provided by the National Highway Traffic Safety Administration.
+- **Fast** &mdash; Vehicle data is included and periodically updated, so validation and decoding are fast.
+
+## Vehicle Identification Number
+
+A ``VIN`` is a unique 17-character Vehicle Identification Number.
+
+* Assigned by vehicle manufacturers
+* Uniquely identifies vehicles manufactured for sale or use in the United States since 1980
+* Governed by the U.S. National Highway Traffic Safety Administration (NHTSA)
+
+The structure of the VIN is:
+
+                                      model year
+                                          |
+                 WMI          check digit | plant
+               |-----|                 |  |  |  |--- serial ----|
+    Position   1  2  3  4  5  6  7  8  9  10 11 12 13 14 15 16 17
+                        |-----------|     |---------------------|
+                             VDS                    VIS
+
+The World Manufacturer Identifier (WMI) holds the country, region, and
+name of the vehicle manufacturer. Mass-market manufacturers are assigned
+a three-character WMI. Specialized manufacturers are assigned a six-
+character WMI (positions 1-3 and 12-14)
+
+The Vehicle Description Section (VDS) is defined by manufacturers to
+identify the vehicle make, model, body type, engine type, restraints,
+and the weight class (for trucks and multi-purpose vehicles).
+
+The Vehicle Identification Section (VIS) identifies the model year,
+plant where the vehicle was made, and the vehicle's serial number.
+
+For more information, see the [VIN specification](https://www.ecfr.gov/current/title-49/subtitle-B/chapter-V/part-565).
+
+Installation
+------------
+
+Use ``pip`` to install the library:
+
+    $ pip install vin
+
+## Vehicle Data
+
+Vehicle data is provided by the U.S. National Highway Traffic Safety Administration (NHTSA) [Product Information Catalog and Vehicle Listing (vPIC)](https://vpic.nhtsa.dot.gov).
+
+## License
+
+VIN is distributed under the terms of the [MIT](https://spdx.org/licenses/MIT.html) license.
+
diff --git a/docs/requirements.txt b/docs/requirements.txt
diff --git a/docs/source/api.rst b/docs/source/api.rst
diff --git a/docs/source/changelog.rst b/docs/source/changelog.rst
diff --git a/docs/source/conf.py b/docs/source/conf.py