Skip to content

Commit

Permalink
added documentation
Browse files Browse the repository at this point in the history
  • Loading branch information
davidpeckham committed Feb 1, 2024
1 parent 2d7bb7d commit b09db7b
Show file tree
Hide file tree
Showing 16 changed files with 332 additions and 25 deletions.
Original file line number Diff line number Diff line change
Expand Up @@ -23,21 +23,21 @@ jobs:
- name: Lint code
run: hatch run lint:style

# lint-typing:
# runs-on: ubuntu-latest
# steps:
# - uses: actions/checkout@vv4.1.1
# - name: Set up Python
# uses: actions/setup-python@v5
# with:
# python-version: "3.11"
# - name: Install dependencies
# run: |
# pip install hatch
# pip install hatch-vcs
# pip install hatch-fancy-pypi-readme
# - name: Lint typing
# run: hatch run lint:typing
lint-typing:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4.1.1
- name: Set up Python
uses: actions/setup-python@v5
with:
python-version: "3.11"
- name: Install dependencies
run: |
pip install hatch
pip install hatch-vcs
pip install hatch-fancy-pypi-readme
- name: Lint typing
run: hatch run lint:typing

test:
runs-on: ubuntu-latest
Expand Down
File renamed without changes.
15 changes: 15 additions & 0 deletions .readthedocs.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,15 @@
version: 2

build:
os: "ubuntu-20.04"
tools:
python: "3.10"

sphinx:
configuration: docs/source/conf.py

python:
install:
- requirements: docs/requirements.txt
- method: pip
path: .
26 changes: 26 additions & 0 deletions CHANGELOG.rst
Original file line number Diff line number Diff line change
@@ -0,0 +1,26 @@
.. _changelog:

Changelog
=========

Versions follow `Semantic Versioning <http://www.semver.org>`_

`0.0.2`_ - 2024-02-01
---------------------

Added
~~~~~
* Documentation

Changed
~~~~~~~
* Renamed GitHub workflows as .yml (from .yaml)
* The method :meth:`.VIN.is_vin_character` now returns False instead of raising ValueError
* Fixed VIN_CHARACTERS assignment in constants.py

`0.0.1`_ - 2024-01-31
---------------------

Added
~~~~~
* First public release
104 changes: 104 additions & 0 deletions README.rst
Original file line number Diff line number Diff line change
@@ -0,0 +1,104 @@
.. begin-html-header
.. raw:: html

<p align="center">
<br />
<a href=""https://vin.readthedocs.io>
<img src="./logo.png" width="360" alt="vin" />
</a>
<br />
<br />
<br />
</p>
<p align="center">
<a href="https://pypi.python.org/pypi/vin">
<img src="https://img.shields.io/pypi/v/vin.svg?style=flat-square" />
</a>
<a href="https://codecov.io/gh/davidpeckham/vin">
<img src="https://img.shields.io/codecov/c/github/davidpeckham/vin.svg?style=flat-square" />
</a>
<a href="https://github.com/davidpeckham/vin/actions?query=workflow%3Alint-and-test">
<img src="https://img.shields.io/github/actions/workflow/status/davidpeckham/vin/lint-and-test.yml?style=flat-square&brach=main" />
</a>
<a href="https://vin.readthedocs.io">
<img src="https://readthedocs.org/projects/vin/badge/?version=latest&style=flat-square" />
</a>
<a href="https://black.readthedocs.io/en/stable/index.html">
<img src="https://img.shields.io/badge/code%20style-black-000000.svg?style=flat-square" />
</a>
</p>

.. end-html-header
.. teaser-begin
A ``VIN`` is a *unique 17-character Vehicle Identification Number*.

* Assigned by vehicle manufacturers
* Governed by the U.S. National Highway Traffic Safety Administration (NHTSA)
* Uniquely identifies vehicles manufacture for sale or use in the United States since 1980

The structure of the VIN is:

.. code-block:: text
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.

Use :class:`VIN`-object by calling the default constructor with the
17-character VIN string. To encode the VIN, convert it to a string:

>>> vin = VIN("4T1BE46K19U856421")
>>> str(vin)
'4T1BE46K19U856421'

For more information, see the
`specification <https://www.ecfr.gov/current/title-49/subtitle-B/chapter-V/part-565>`_.

.. teaser-end
.. installation-begin
Installation
------------

Use ``pip`` to install the library

.. code-block:: bash
$ pip install vin
.. installation-end
.. usage-begin
Basic Usage
-----------

Create a new ``VIN`` object from a 17-character string

.. code-block:: pycon
>>> from vin import VIN
>>> VIN('4T1BE46K19U856421')
VIN(4T1BE46K19U856421)
.. usage-end
20 changes: 20 additions & 0 deletions docs/Makefile
Original file line number Diff line number Diff line change
@@ -0,0 +1,20 @@
# Minimal makefile for Sphinx documentation
#

# You can set these variables from the command line, and also
# from the environment for the first two.
SPHINXOPTS ?=
SPHINXBUILD ?= sphinx-build
SOURCEDIR = source
BUILDDIR = _build

# Put it first so that "make" without argument is like "make help".
help:
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

.PHONY: help Makefile

# Catch-all target: route all unknown targets to Sphinx using the new
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
%: Makefile
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
1 change: 1 addition & 0 deletions docs/requirements.txt
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
furo
13 changes: 13 additions & 0 deletions docs/source/api.rst
Original file line number Diff line number Diff line change
@@ -0,0 +1,13 @@
.. _api:

Developer Interface
===================

.. module:: vin


VIN
---

.. autoclass:: VIN
:members:
1 change: 1 addition & 0 deletions docs/source/changelog.rst
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
.. include:: ../../CHANGELOG.rst
87 changes: 87 additions & 0 deletions docs/source/conf.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,87 @@
import os
import sys
from datetime import datetime


sys.path.insert(0, os.path.abspath("../.."))

import vin # noqa


copyright = f"{datetime.now().year}, David Peckham"
author = "David Peckham"
master_doc = "index"
source_suffix = [".rst", ".md"]

# The full version, including alpha/beta/rc tags
release = vin.__version__
version = release.rsplit(".", 1)[0]

# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
extensions = [
"sphinx.ext.autodoc",
"sphinx.ext.napoleon",
"sphinx.ext.viewcode",
]

# 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", "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_logo = "../logo.png"
html_theme = "furo"
html_theme_options = {
"github_user": "davidpeckham",
"github_repo": "vin",
"description": "A library for working with VINs",
"sidebar_collapse": False,
"logo_text_align": "center",
}

html_title = "VIN docs"

# If false, no index is generated.
html_use_index = True

# If true, the index is split into individual pages for each letter.
html_split_index = False

# If true, links to the reST sources are added to the pages.
html_show_sourcelink = True

# If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
html_show_sphinx = True

# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
html_show_copyright = True

html_sidebars = {
"**": [
"sidebar/scroll-start.html",
"sidebar/brand.html",
"sidebar/search.html",
"sidebar/navigation.html",
"sidebar/ethical-ads.html",
"sidebar/scroll-end.html",
]
}

# 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"]
pygments_style = "sphinx"

autodoc_member_order = "groupwise"
35 changes: 35 additions & 0 deletions docs/source/index.rst
Original file line number Diff line number Diff line change
@@ -0,0 +1,35 @@
VIN
===

Release v\ |release| (:ref:`What's new <changelog>`)


.. include:: ../../README.rst
:start-after: teaser-begin
:end-before: teaser-end

.. include:: ../../README.rst
:start-after: installation-begin
:end-before: installation-end

.. include:: ../../README.rst
:start-after: usage-begin
:end-before: usage-end

.. include:: ../../README.rst
:start-after: cli-begin
:end-before: cli-end

API documentation
-----------------

.. toctree::
:maxdepth: 2

api

.. toctree::
:maxdepth: 1

changelog

4 changes: 2 additions & 2 deletions hatch.toml
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@ dependencies = [

[envs.default.scripts]
test = "pytest {args:.}"
cov-test = "pytest --cov {args:ulid} --cov-report=term-missing --cov-report=xml"
cov-test = "pytest --cov {args:vin} --cov-report=term-missing --cov-report=xml"

[envs.lint]
dependencies = [
Expand All @@ -17,7 +17,7 @@ dependencies = [
]

[envs.lint.scripts]
typing = "mypy --install-types --non-interactive {args:ulid}"
typing = "mypy --install-types --non-interactive {args:src/vin}"
style = [
"black --check --diff {args:.}",
"ruff {args:.}",
Expand Down
10 changes: 8 additions & 2 deletions pyproject.toml
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
[build-system]
requires = ["hatchling"]
requires = ["hatchling", "hatch-vcs", "hatch-fancy-pypi-readme"]
build-backend = "hatchling.build"

[project]
Expand Down Expand Up @@ -89,7 +89,6 @@ exclude_lines = [
line-length = 100

[tool.ruff]
target-version = "py39"
line-length = 100
select = ["A", "B", "C", "C4", "E", "F", "I", "N", "PT", "Q", "RUF", "S", "SIM", "T10", "UP", "W", "YTT"]
fixable = ["RUF100", "I001"]
Expand All @@ -116,3 +115,10 @@ line_length = 100

[tool.doc8]
max-line-length = 100

[tool.hatch.metadata.hooks.fancy-pypi-readme]
content-type = "text/x-rst"

[[tool.hatch.metadata.hooks.fancy-pypi-readme.fragments]]
path = "README.rst"
start-after = ".. teaser-begin"
2 changes: 1 addition & 1 deletion src/vin/__about__.py
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
# SPDX-FileCopyrightText: 2024-present David Peckham <[email protected]>
#
# SPDX-License-Identifier: MIT
__version__ = "0.0.1"
__version__ = "0.0.2"
Loading

0 comments on commit b09db7b

Please sign in to comment.