Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Start advanced documentation #98

Merged
merged 11 commits into from
Dec 17, 2020
Merged

Start advanced documentation #98

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
11 commits
Select commit Hold shift + click to select a range
8d5d5f1
Remove quistart from README
oncleben31 Dec 13, 2020
e13354b
Transfer quickstart content in documentation
oncleben31 Dec 13, 2020
a352e0f
Transfer inline doc in repostory documentation
oncleben31 Dec 13, 2020
21801bf
Fix missing semicolon
oncleben31 Dec 13, 2020
acb3372
Add a link to documentation in template
oncleben31 Dec 13, 2020
8ac4071
Translate content in reStructuredTex
oncleben31 Dec 13, 2020
abaa191
Fix missed blueprint new name
oncleben31 Dec 13, 2020
5f9f6a3
Move devcontainer documentation
oncleben31 Dec 13, 2020
4956141
Code style cleaning
oncleben31 Dec 13, 2020
8d40850
Create structure of document
oncleben31 Dec 13, 2020
e5db64b
Add additional section in structure
oncleben31 Dec 17, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
172 changes: 9 additions & 163 deletions README.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -26,14 +26,16 @@ cookiecutter-homeassistant-custom-component

.. badges-end
|
.. introduction-begin
Cookiecutter_ template for a `Home Assistant`_ custom component based on the
integration_blueprint_ template.
This repository is a Cookiecutter_ template for a `Home Assistant`_ custom component
based on the integration_blueprint_ template.

This project is the fusion of `cookiecutter-homeassistant-component`_, integration_blueprint_
This project is sort of fusion of `cookiecutter-homeassistant-component`_, integration_blueprint_
and `cookiecutter-hypermodern-python`_ projects.

.. introduction-end
✨📚✨ `Read the full documentation`__

__ https://cookiecutter-homeassistant-custom-component.readthedocs.io/
Expand All @@ -46,7 +48,8 @@ Usage
.. parsed-literal::
$ cookiecutter gh:oncleben31/cookiecutter-homeassistant-custom-component --checkout=\ |current-stable-version|\
$ cookiecutter gh:oncleben31/homeassistant-custom-component \\
--checkout=\ |current-stable-version|\
.. usage-end
Expand All @@ -69,173 +72,16 @@ in the `cookiecutter-homeassistant-custom-component-instance`_ example.

.. features-end
Quickstart
==========

.. quickstart-begin
Requirements
------------

Install Cookiecutter_:

.. code:: console
$ pipx 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, or 3.9 using pyenv_.


Creating a project
------------------

Generate a Home Assistant custom component project by using the following command:

.. parsed-literal::
$ cookiecutter gh:oncleben31/cookiecutter-homeassistant-custom-component --checkout=\ |current-stable-version|\
Follow the instructions to customize the generated project

===================== ============================================
Setting Definition
===================== ============================================
``friendly_name`` Integration name used in configuration UI.
``project_name`` Project name on GitHub.
``domain_name`` Integration domain name
``class_name_prefix`` Prefix to be use in classes name
``github_user`` GitHub user hosting the repository
``version`` Initial version of the component
===================== ============================================

Change to the root directory of your new project,
and create a Git repository:

.. code:: console
$ git init
$ git add .
$ git commit
Setup the development container
-------------------------------

The development container allows to work in a local and dedicated Home Assitant instance
to test your custom component.
To launch it you need to have already installed Docker_, `Visual Studio Code`_ (VSC)
and the `Visual Studio Code Remote - Containers`_ extension.

Open your local copy of the repository with VSC:

.. code:: console
$ code .
Visual Studio Code starts and you are asked to "Reopen in Container",
this will start the build of the container.

When done, you can launch the local instance of Home Assistant by running the task ``Run Home Assistant on port 9123``.

Use your preferred browser to open the URL ``http://localhost:9123``.

Initalize your Home Assistant local instance by following the onboarding workflow.

When setup, you can go to **Configuration** -> **Integrations** menu, clic the ``+`` button
and search the name you have given to the custom component.

Follow the config flow of the custom component to integrate it in Home Assistant.

Now you are all set to modify the code and develop your ideas !


Advanced usages
---------------

Add a logo
^^^^^^^^^^

You have the possibility to add a logo to be used in the integrations configuration UI.
To do so, visit the `home-assistant/brands`_ repository on GitHub
and follow the instructions.

Step by step debugging
^^^^^^^^^^^^^^^^^^^^^^

Step by step debugging is easy with Visual Studio Code.
You have to install in Home Assistant the `PTVSD`_ integration
and follow the documentation instructions to setup VSC.
Then you will be able to connect the VSC debuger to the local Home Assistant instance.

Deploy with HACS
^^^^^^^^^^^^^^^^

HACS_ is the community store.
You can ease the installation of your custom component by making it compatible with HACS.

The template have already the tools do do that: ``hacs.json`` and ``info.md`` files.
The `Publish documentation`_ explains how to set those files
and the different options you have to integrate your custom component in the HACS network.

Step by step debugging
^^^^^^^^^^^^^^^^^^^^^^

If you choose to use Visual Studio Code with the development container, you can
test your custom component in Home Assistant with step by step debugging.

You need to modify the ``configuration.yaml`` file in ``.devcontainer`` folder
by uncommenting the line:

.. code :: yaml
# debugpy
Then launch the task ``Run Home Assistant on port 9123``, and launch the debbuger
with the existing debugging configuration ``Python: Attach Local``.

For more information, look at `the Remote Python Debugger integration documentation`_.

Known limitations
-----------------

- **If you plan to host the generated repository in a GitHub organization you will need manual modifications**.

Currently the template work well when the repostory is hosted in a GitHub individual account,
where URL name and code owner are the same.
If you want to use an organization,
it is recommended to use the name of this organization for ``github_user`` settings
and modify manually where it's needed afer generation with Cookiecutter.


.. quickstart-end
.. references-begin
.. |current-stable-version| replace:: 2020.11.16
.. _Black: https://github.com/psf/black
.. _integration_blueprint: https://github.com/custom-components/integration_blueprint
.. _Cookiecutter: https://github.com/cookiecutter/cookiecutter
.. _cookiecutter-homeassistant-component: https://github.com/boralyl/cookiecutter-homeassistant-component
.. _cookiecutter-homeassistant-custom-component-instance: https://github.com/oncleben31/cookiecutter-homeassistant-custom-component-instance
.. _cookiecutter-hypermodern-python: https://github.com/cjolowicz/cookiecutter-hypermodern-python
.. _Docker: https://www.docker.com/
.. _GitHub: https://github.com/
.. _GitHub Actions: https://github.com/features/actions
.. _HACS: https://hacs.xyz/
.. _Home Assistant: https://www.home-assistant.io/
.. _Home Assistant developers documentation: https://developers.home-assistant.io/
.. _home-assistant/brands: https://github.com/home-assistant/brands
.. _Hypermodern Python: https://cjolowicz.github.io/posts/hypermodern-python-01-setup/
.. _pipx: https://pipxproject.github.io/pipx/
.. _pre-commit: https://pre-commit.com/
.. _PTVSD: https://www.home-assistant.io/integrations/ptvsd/
.. _Publish documentation: https://hacs.xyz/docs/publish/start
.. _pyenv: https://github.com/pyenv/pyenv
.. _the Remote Python Debugger integration documentation: https://www.home-assistant.io/integrations/debugpy/
.. _Visual Studio Code: https://code.visualstudio.com/
.. _Visual Studio Code Remote - Containers: https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers

.. references-end
Loading