Implement advanced documentation

LICENSE.rst

@@ -1,7 +1,7 @@
 MIT License
 ===========
 
-Copyright © 2020 Onclben31
+Copyright © 2020 oncleben31
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

README.rst

@@ -74,13 +74,13 @@ Install Cookiecutter_:
 
 pipx_ is preferred, but you can also install with ``pip install --user``.
 
-It is recommended to set up Python 3.7, 3.8, and 3.9 using pyenv_.
+It is recommended to set up Python 3.7, 3.8, or 3.9 using pyenv_.
 
 
 Creating a project
 ------------------
 
-Generate a Python project:
+Generate a Home Assistant custom component project:
 
 .. code:: console
 
@@ -112,7 +112,8 @@ and create a Git repository:
 .. _GitHub Actions: https://github.com/features/actions
 .. _HACS: https://hacs.xyz/
 .. _Home Assistant: https://www.home-assistant.io/
-.. _Hypermodern Python: https://medium.com/@cjolowicz/hypermodern-python-d44485d9d769
+.. _Home Assistant developers documentation: https://developers.home-assistant.io/
+.. _Hypermodern Python: https://cjolowicz.github.io/posts/hypermodern-python-01-setup/
 .. _pipx: https://pipxproject.github.io/pipx/
 .. _pre-commit: https://pre-commit.com/
 .. _pyenv: https://github.com/pyenv/pyenv

docs/conf.py

@@ -0,0 +1,24 @@
+"""Sphinx configuration."""
+from datetime import datetime
+
+
+project = "Home Assistant Custom Component Cookiecutter"
+author = "Oncleben31"
+copyright = f"{datetime.now().year}, {author}"
+# extensions = ["sphinx.ext.intersphinx"]
+# intersphinx_mapping = {"mypy": ("https://mypy.readthedocs.io/en/stable/", None)}
+language = "en"
+# html_static_path = ["_static"]
+html_theme = "alabaster"
+html_theme_options = {
+    "github_banner": "true",
+    "github_button": "true",
+    "github_count": "true",
+    "github_user": "oncleben31",
+    "github_repo": "cookiecutter-homeassistant-custom-component",
+    "github_type": "star",
+    # "logo": "logo.png",
+    "logo_name": "true",
+    "fixed_sidebar": "true",
+    "sidebar_width": "250px",
+}

docs/index.rst

@@ -0,0 +1,50 @@
+Home Assistant custom component Cookiecutter
+============================================
+
+.. toctree::
+   :hidden:
+   :maxdepth: 1
+
+   Quickstart <quickstart>
+   License <license>
+   Changelog <https://github.com/oncleben31/cookiecutter-homeassistant-custom-component/releases>
+
+.. rst-class:: badges
+
+.. include:: ../README.rst
+   :start-after: badges-begin
+   :end-before: badges-end
+
+Cookiecutter_ template for a Home Assistant custom component
+based on the `blueprint`_ repository.
+
+
+Usage
+-----
+
+.. code:: console
+
+   $ cookiecutter gh:oncleben31/cookiecutter-homeassistant-custom-component \
+     --checkout="2020.10.30"
+
+
+Features
+--------
+
+.. include:: ../README.rst
+   :start-after: features-begin
+   :end-before: features-end
+
+
+FAQ
+---
+
+  *What is this project about?*
+
+The mission of this project is to provide Home Assistant custom component developers a
+ready-to-use template with best practices from `Home Assistant developers documentation`_ and from
+`Hypermodern Python`_ blog articles.
+
+.. include:: ../README.rst
+   :start-after: references-begin
+   :end-before: references-end

docs/license.rst

@@ -0,0 +1 @@
+.. include:: ../LICENSE.rst

docs/quickstart.rst

@@ -0,0 +1,10 @@
+Quickstart Guide
+================
+
+.. include:: ../README.rst
+   :start-after: quickstart-begin
+   :end-before: quickstart-end
+
+.. include:: ../README.rst
+   :start-after: references-begin
+   :end-before: references-end

docs/requirements.txt

@@ -0,0 +1,2 @@
+sphinx==3.2.1
+sphinx-autobuild==2020.9.1

noxfile.py

@@ -0,0 +1,26 @@
+"""Nox sessions."""
+from pathlib import Path
+import shutil
+
+import nox
+from nox.sessions import Session
+
+
+@nox.session
+def docs(session: Session) -> None:
+    """Build the documentation."""
+    args = session.posargs or ["-W", "-n", "docs", "docs/_build"]
+
+    if session.interactive and not session.posargs:
+        args = ["-a", "--watch=docs/_static", "--open-browser", *args]
+
+    builddir = Path("docs", "_build")
+    if builddir.exists():
+        shutil.rmtree(builddir)
+
+    session.install("-r", "docs/requirements.txt")
+
+    if session.interactive:
+        session.run("sphinx-autobuild", *args)
+    else:
+        session.run("sphinx-build", *args)