From 0655ce48f7aa08beb4100840db694b1d53c18a8d Mon Sep 17 00:00:00 2001 From: Stefano Pigozzi Date: Wed, 18 Nov 2020 21:27:05 +0100 Subject: [PATCH] =?UTF-8?q?=F0=9F=93=94=20Add=20install=20and=20usage=20do?= =?UTF-8?q?cumentation?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- bbbdl/urlhandler.py | 2 +- docs/source/autodoc/index.rst | 22 +++---- docs/source/index.rst | 8 ++- docs/source/installation/fork.png | Bin 0 -> 1611 bytes docs/source/installation/index.rst | 92 +++++++++++++++++++++++++++++ docs/source/usage/index.rst | 69 ++++++++++++++++++++++ 6 files changed, 179 insertions(+), 14 deletions(-) create mode 100644 docs/source/installation/fork.png create mode 100644 docs/source/installation/index.rst create mode 100644 docs/source/usage/index.rst diff --git a/bbbdl/urlhandler.py b/bbbdl/urlhandler.py index 1881a2f..0f0bc50 100644 --- a/bbbdl/urlhandler.py +++ b/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. diff --git a/docs/source/autodoc/index.rst b/docs/source/autodoc/index.rst index fd885fe..bf7f8ae 100644 --- a/docs/source/autodoc/index.rst +++ b/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 diff --git a/docs/source/index.rst b/docs/source/index.rst index 6851992..29a4321 100644 --- a/docs/source/index.rst +++ b/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 diff --git a/docs/source/installation/fork.png b/docs/source/installation/fork.png new file mode 100644 index 0000000000000000000000000000000000000000..c91694663f0a86db1b0c9a2591ad4de15cdfcc10 GIT binary patch literal 1611 zcmV-R2DJH!P)-O!zHN0fMI`Z0?HKeg_tN&z(<_;BnC+ojS517 zA`oE&k*5JP{6Ul%YsQ#lbD|)y&BTp`!s_~1Zy)RYV{Yzlogiy3ZFWD&O?uDo+;e{I zx94|$=iH+S1VbIDBm_y<+5wd-M-?l9P{m3hRIw5WRjdR;*Pp@dapP`v;|~Os^e67n zX%+fEYrtSIkeZrGYN|1EmENg)I2@+=d^1{|7Eu&Q5d=kijYrPa)iZAFO^Wp=NfJ({ zllG1d(uSvzlqCP7^ch*r=bJGPHDfZF=;-Jm+@UVRltK^$($mv%I-NKi4n~X^A+yV* zbG5qB>a>`QMmkiHt{E1K1#OZBug4=Rmx<-^xDiDWRisgEeYBiY64zl?EM3bH)7?Dv>O>m1ZD8Zl z<)rP~&cdvLH667uxVh|0+I&82IpZm}S5R41-EFI^s;1n23|r24+I&7Xm+iW`PJDk- zzT*>CzV$9|uKt`|H5Um2(7=vWJ1MU@#QUqZWAB;q2LI&X+BK}N=&BoIP93M(4O5?8 zN$G=&SpDMNBnN8wzQ#4+rlTfSi?fxnH)T>dv*4fmzk1j@KNrp{U~E>V%y#8S)b8I& zxqdoJUVnwx9?j;$!JQm#>aw53esVOAEq{b*UC}al5qsGlPK}$#lljAy8L8Qe*ziRe zD`%JiaJeo4Cd}r6XW3B;g9X!Wr`&#w+LNad1Ornh<#pSpOv>Y^y@K~Y-q>CDzX<)h zm(o}E{_AAgG+tOXniIc^6g-!WRS%5Hr|^~v_Sambcocw$ZF(Lf^gsx}L*?%6oN#2b zWYK6+qV+{DhdG11+|K#Q|J!bse^dq8Pq6TgI1+1aaUpGz#POeMC|$OgVOFu*Hq0tg zx@<9TzqghtlX96`T=?HkMVhmG)wnTY?U7?x(~P(rT`|vy)%33|35@9XS{`yhl(gE9LcFeKhUVigazQ|+_q;ZdFe3BSj~a0FLPH~bXtyT>fSrt z^+pg3*mAP3u5o=Pw`CpT;E}W3S~7-|3soFBspIBFBY}np59rYA!JJ#jjH8>_|I=ia zK${N`4imF&$;jZ@AQ%F9E$`hR#;ndsm z5K;teIoY!C`2P^FmCUDQ_aWB2wTEEJNNmOPDH?UT=Y~^IJb@o~9HBOM9<~@yUjCo$ zR0jY~vv1Ss?(#c_-#cKjWbd=;>l?W7#>@dV*pqdiZUtcJ(~n23O(m(XZ&37oR&VO+ z>bd@g8@lgfw%z3ONl52Kd>KbS| z-^`q%SAQjRe literal 0 HcmV?d00001 diff --git a/docs/source/installation/index.rst b/docs/source/installation/index.rst new file mode 100644 index 0000000..f18d34a --- /dev/null +++ b/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+ `_ +* `ffmpeg `_ + + +Installing bbbdl +---------------- + +bbbdl is distributed through `PyPI, the Python Package Index `_. + + +Using pipx +~~~~~~~~~~ + +The easiest way to install bbbdl, but requires `pipx `_ 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 `_ and `Poetry `_, 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 diff --git a/docs/source/usage/index.rst b/docs/source/usage/index.rst new file mode 100644 index 0000000..a8d78e0 --- /dev/null +++ b/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