📔 Add install and usage documentation

bbbdl/urlhandler.py

@@ -6,7 +6,7 @@ playback_regex = re.compile(r"^(https?://.+)/playback/presentation/2\.0/playback
 "The regex used to parse BigBlueButton playback urls."
 
 
-def playback_to_data(url) -> Sequence[str]:
+def playback_to_data(url: str) -> Sequence[str]:
     """
     Autodetect the base url and the meeting id from a BigBlueButton playback url.
 

docs/source/autodoc/index.rst

@@ -1,12 +1,12 @@
-API Reference
-===========================
+Python API
+==========
 
-Welcome to the autogenerated documentation of bbbdl!
+The modules of bbbdl can be used in other Python software by adding bbbdl to their dependencies and importing them at
+the start of the file.
 
-It may be incomplete or outdated, as it is automatically updated.
+.. note:: The following sections section is autogenerated from bbbdl's Python code.
 
-
-Composer module
+bbbdl.composer
 ---------------
 
 .. currentmodule:: bbbdl.composer
@@ -14,7 +14,8 @@ Composer module
    :members:
    :undoc-members:
 
-Resources module
+
+bbbdl.resources
 ----------------
 
 .. currentmodule:: bbbdl.resources
@@ -23,7 +24,7 @@ Resources module
    :undoc-members:
 
 
-Tracks module
+bbbdl.tracks
 -------------
 
 .. currentmodule:: bbbdl.tracks
@@ -32,7 +33,7 @@ Tracks module
    :undoc-members:
 
 
-Url handler module
+bbbdl.urlhandler
 ------------------
 
 .. currentmodule:: bbbdl.urlhandler
@@ -40,7 +41,8 @@ Url handler module
    :members:
    :undoc-members:
 
-Errors and exceptions
+
+bbbdl.exc
 ---------------------
 
 .. currentmodule:: bbbdl.exc

docs/source/index.rst

@@ -1,14 +1,16 @@
 bbbdl
 =================================
 
-Welcome to the documentation of bbbdl!
+A tool for downloading BigBlueButton meetings
 
-Table of contents
------------------
+Documentation
+-------------
 
 .. toctree::
    :maxdepth: 3
 
+   installation/index
+   usage/index
    autodoc/index
 
 Useful links

docs/source/installation/index.rst

@@ -0,0 +1,92 @@
+Installation
+============
+
+Requirements
+------------
+
+You can install bbbdl on any computer which the following software already installed:
+
+* `Python 3.8+ <https://www.python.org/>`_
+* `ffmpeg <https://ffmpeg.org/download.html>`_
+
+
+Installing bbbdl
+----------------
+
+bbbdl is distributed through `PyPI, the Python Package Index <https://pypi.org/project/bbbdl/>`_.
+
+
+Using pipx
+~~~~~~~~~~
+
+The easiest way to install bbbdl, but requires `pipx <https://pipxproject.github.io/pipx/installation/>`_ to be
+installed separately.
+
+Run the following command in a terminal or command prompt:
+
+.. code-block:: bash
+
+   pipx install bbbdl
+
+This will install bbbdl for the current user in an isolated environment so that the dependencies don't conflict with
+other software already on your system.
+
+
+Using pip and venv
+~~~~~~~~~~~~~~~~~~
+
+If pipx is not available, you can manually install bbbdl in a virtual environment (venv).
+
+First, create a venv:
+
+.. code-block:: bash
+
+   python -m venv venv
+
+Then, enter the venv:
+
+.. code-block:: bash
+
+   # Assuming you're using Linux
+   source venv/bin/activate
+
+While inside the venv, install bbbdl with pip:
+
+.. code-block:: bash
+
+   pip install bbbdl
+
+Done! Remember that, if you install bbbdl using this method, you'll need to have entered the venv in that terminal
+session to use bbbdl!
+
+
+For development
+~~~~~~~~~~~~~~~
+
+If you want to contribute to bbbdl, you'll need to install it from source in editable mode.
+
+This requires `Git <https://git-scm.com/>`_ and `Poetry <https://python-poetry.org/docs/#installation>`_, ensure to have
+both of them installed.
+
+First, fork the repository on GitHub:
+
+.. image:: fork.png
+
+Then, clone the forked repository on your computer and enter the created directory:
+
+.. code-block:: bash
+
+   git clone https://github.com/YOUR-USERNAME-HERE/bbbdl
+   cd bbbdl
+
+Finally, automatically create a venv and install all dependencies with Poetry:
+
+.. code-block:: bash
+
+   poetry install
+
+This installs bbbdl in a Poetry venv, which you can access with:
+
+.. code-block:: bash
+
+   poetry shell

docs/source/usage/index.rst

@@ -0,0 +1,69 @@
+Usage
+=====
+
+Once installed, bbbdl can be run from the command line.
+
+bbbdl has multiple operating modes; to view them all, run:
+
+.. code-block:: bash
+
+   bbbdl --help
+
+Download mode
+-------------
+
+Download mode is used to download and render a single meeting.
+
+This will download and render the meeting at ``MEETING_URL`` and save it as ``OUTPUT_FILE_NAME.mp4``.
+
+.. code-block:: bash
+
+   # bbbdl download -i MEETING_URL -o OUTPUT_FILE_NAME.mp4
+
+You can specify a different extension as output file, and ffmpeg will render the video using that codec.
+
+Additional options can be specified; to view the complete list, run:
+
+.. code-block:: bash
+
+   bbbdl download --help
+
+Sync mode
+---------
+
+Sync mode is used to batch download all available meetings from a list file, skipping files that were already downloaded
+so to not download and render them twice.
+
+List file
+~~~~~~~~~
+
+The list file is a JSON file, containing a single object with filenames as keys and meeting urls as values:
+
+.. code-block:: json
+
+   {
+       "example-1.mp4": "https://example.org/playback/presentation/2.0/playback.html?meetingId=aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa-1111111111111",
+       "example-2.mkv": "https://example.org/playback/presentation/2.0/playback.html?meetingId=bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb-2222222222222"
+   }
+
+It can be on the local machine, or available through HTTPS.
+
+Syncing from a local list file
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If the JSON file is saved on your computer as `FILENAME.json`, you can sync the contents of the list file with the
+current folder by running:
+
+.. code-block:: bash
+
+   bbbdl sync -f FILENAME.json
+
+
+Syncing from a remote list file
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+To sync using a JSON file provided through HTTPS, you can run:
+
+.. code-block:: bash
+
+   bbbdl sync -r https://example.org/my-remote-list.json