Updated installation, configuration and usage information. (#54)

* add installation process
mainly to add the extension package name which was a request of one of my colleague (looking for a youtube package for 3 days)

Fix #48

* contribution and usage fixes

* list formatting

---------

Co-authored-by: Pierrick Rambaud <pierrick.rambaud49@gmail.com>

CONTRIBUTE.rst

@@ -10,7 +10,8 @@ Currently, the project uses four automation processes (called sessions) in ``nox
 -   ``docs``: to build the documentation in the ``build`` folder;
 -   ``lint``: to run the pre-commits in an isolated environment
 
-Every nox session is run in its own virtual environment, and the dependencies are installed automatically.
+Every nox session is run in its own virtual environment, and the dependencies
+are installed automatically.
 
 To run a specific nox automation process, use the following command:
 
@@ -36,7 +37,7 @@ See the following sections for more details.
 Clone the repository
 ^^^^^^^^^^^^^^^^^^^^
 
-First off, you'll need your own copy of **sphinxcontrib-youtube** codebase. You can clone it for local development like so:
+First off, you'll need your own copy of the **sphinxcontrib-youtube** codebase.
 
 Fork the repository so you have your own copy on GitHub. See the `GitHub forking guide for more information <https://docs.github.com/en/get-started/quickstart/fork-a-repo>`__.
 
@@ -53,42 +54,54 @@ Then install the development version of the extension:
 
    pip install -e .[dev]
 
-This will install the **sphinxcontrib-youtube** library, together with two additional tools:
--   `pre-commit <https://pre-commit.com>`__ for automatically enforcing code standards and quality checks before commits.
--   `nox <https://nox.thea.codes/en/stable/>`__, for automating common development tasks.
+This will install the **sphinxcontrib-youtube** library, together with two
+additional tools: 
+
+- `pre-commit <https://pre-commit.com>`__ for automatically
+  enforcing code standards and quality checks before commits. 
+- `nox <https://nox.thea.codes/en/stable/>`__, for automating
+  common development tasks.
 
 Lastly, activate the pre-commit hooks by running:
 
 .. code-block:: console
 
     pre-commit install
 
-This will install the necessary dependencies to run pre-commit every time you make a commit with Git.
+This will install the necessary dependencies to run pre-commit every time you
+make a commit with Git.
 
 Contribute to the codebase
 ^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-Any larger updates to the codebase should include tests and documentation. The tests are located in the ``tests`` folder, and the documentation is located in the ``docs`` folder.
+Any larger updates to the codebase should include tests and documentation. The
+tests are located in the ``tests`` folder, and the documentation is located in
+the ``docs`` folder.
 
 To run the tests locally, use the following command:
 
 .. code-block:: console
 
     nox -s test
 
-See :ref:`below <contributing-docs>` for more information on how to update the documentation.
+See :ref:`below <contributing-docs>` for more information on how to update the
+documentation.
 
 .. _contributing-docs:
 
 Contribute to the docs
 ^^^^^^^^^^^^^^^^^^^^^^
 
-The documentation is built using `Sphinx <https://www.sphinx-doc.org/en/master/>`__ and deployed to `Read the Docs <https://readthedocs.org/>`__.
+<https://www.sphinx-doc.org/en/master/>`__ and deployed to `Read the Docs
+The documentation is built using `Sphinx
+<https://readthedocs.org/>`__.
 
 To build the documentation locally, use the following command:
 
 .. code-block:: console
 
     nox -s docs
 
-For each pull request, the documentation is built and deployed to make it easier to review the changes in the PR. To access the docs build from a PR, click on the "Read the Docs" preview in the CI/CD jobs.
+For each pull request, the documentation is built and deployed to make it
+easier to review the changes in the PR. To access the docs build from a PR,
+click on the "Read the Docs" preview in the CI/CD jobs.

docs/index.rst

@@ -25,8 +25,6 @@ This module defines directives, youtube and vimeo which insert videos from the r
 Documentation contents
 ----------------------
 
-The documentation contains 2 main sections:
-
 .. grid:: 1 2 2 2
 
    .. grid-item::
@@ -41,4 +39,4 @@ The documentation contains 2 main sections:
       .. card:: Contribute
          :link: contribute.html
 
-         Help us improve the lib.
+         Help us improve the library.

docs/usage.rst

@@ -20,14 +20,38 @@ This module defines directives, :code:`youtube` and :code:`vimeo` which insert v
 
    .. vimeo:: 148751763
 
-.. vimeo:: 148751763
+.. vimeo:: 486557682
    :align: center
    :aspect: 16:9
 
 Usage
 -----
 
-The referenced video will be embedded into HTML and Latex outputs, the behaviour will be slightly different for obvious reasons.
+The referenced video will be embedded into HTML and LaTeX outputs, the behaviour will be different as LaTeX cannot display videos.
+
+Installation
+^^^^^^^^^^^^
+
+The package is avalaible on `pipy <https://pypi.org/project/sphinxcontrib-youtube/1.2.0/>`__ and can be installed with pip:
+
+.. code-block:: console
+
+   pip install sphinxcontrib-youtube
+
+Configuration
+^^^^^^^^^^^^^
+
+Add `"sphinxcontrib.youtube"` to the `extensions` list in :file:`conf.py`. For
+example:
+
+.. code-block:: python3
+
+   extensions = [
+       'sphinx.ext.intersphinx',
+       'sphinxcontrib.youtube'
+   ]
+
+
 
 HTML
 ^^^^
@@ -78,12 +102,12 @@ To start the video at a specific time the parameter "url_parameters" may be used
 
 .. code-block:: rst
 
-   .. vimeo:: 148751763
+   .. vimeo:: 486557682
       :url_parameters: "#t=0m43s"
 
 When generating the EPUB output, the videos will not be embedded. Instead, a link to the video will be added.
 
-Latex
+LaTeX
 ^^^^^
 
 In LaTeX output, the following code will be emitted for the videos:
@@ -102,7 +126,7 @@ The user may customise the rendering of the URL by defining this command in the
 
    # conf.py
    # ...
-   # -- Option for Latex output ---------------------------------------------------
+   # -- Option for LaTeX output ---------------------------------------------------
 
    # create a custom sphinx output for the youtube and vimeo video
    youtube_cmd = r"\newcommand{\sphinxcontribyoutube}[3]{\begin{figure}\sphinxincludegraphics{{#2}.jpg}\caption{\url{#1#2#3}}\end{figure}}" + "\n"