Iteration 'stable beta 1 - new docs' (#13)

* chore: ➕ Add 'furo' (2022.2.14) RTD theme and remove 'sphinx-rtd-theme'

Also updated:   • markupsafe (2.0.1 -> 2.1.0)   • docutils (0.16 -> 0.17.1)   • filelock (3.5.1 -> 3.6.0)

* build: 👷 Integrate Furo them into Nox sessions and update docs build config

* chore: ⬆️ Upgrade python to ^3.8.0

Were installed:  • zipp (3.7.0)   • importlib-metadata (4.11.1)
Also were updated:  • sphinx (4.3.2 -> 4.4.0)

* docs: 📝 Update boilerplate README

* docs: 📝 Add manpage (renamed usage) and update generated help output (only for download command)

* docs: 📝 Add 'Usage Examples' page

* docs: 📝 Add Motivation page

Add two meta tags on index page

* build: 📝 Update reference.rst bu adding auto generated description for 4 main modules

* docs: 📝 Update Readme using anonymous reference ('double underscores') for licenses links

* docs: 📝 Add detailed docstrings for 'lep.py'

* test(console): ✅ Update two test to fix concurrency issues during paralell tests execution

* docs(downloader): 📝 Add docstrings for 'downloader.py'

* docs(parser): 📝 Add docstrings for 'parser.py'

* docs: 📝 Add docstrings for 'exceptions.py'

* docs: 📝 Fix two little mistakes in lep's docstrings

* style: 🚨 Fix linter errors by 'pre-commit' session

* chore: 🔧 Update .flake8 config to set max-line-length = 80

* docs(console): 📝 Update metavar values for path options and '--episode' option

* docs: 📝 Update links to Example Usage and Man Page, Add link to RTD website only for GitHub

* chore: 🔧 Update config constants with production URLs

* fix: 🐛 Correct 'short_date' property for LepEpisode (must be original date, not after conversion to UTC)

* docs: 📝 Add LEP YouTube link on Readme and update required time and storage for download all episodes

* fix: 🐛 Fix wrong short date again (episode datetime is not converted to UTC now)

* test: ✅ Add tests to check date filter for date close to midnight and updated test with assigning date as datetime

* chore: Bump to 3.0.0b1

* test(console): ✅ Update version checking (just "3.")

.flake8

@@ -1,7 +1,7 @@
 [flake8]
 select = B,B9,C,D,DAR,E,F,N,RST,S,W
 ignore = E203,E501,RST201,RST203,RST301,W503,B950
-max-line-length = 120
+max-line-length = 80
 max-complexity = 10
 docstring-convention = google
 per-file-ignores = tests/*:S101

README.rst

@@ -1,7 +1,9 @@
 LEP Downloader
 ==============
 
-|PyPI| |Python Version| |License|
+.. badges-begin
+
+|PyPI| |Status| |Python Version| |License|
 
 |Read the Docs| |Tests| |Codecov|
 
@@ -10,6 +12,9 @@ LEP Downloader
 .. |PyPI| image:: https://img.shields.io/pypi/v/lep-downloader.svg
    :target: https://pypi.org/project/lep-downloader/
    :alt: PyPI
+.. |Status| image:: https://img.shields.io/pypi/status/lep-downloader.svg
+   :target: https://pypi.org/project/lep-downloader/
+   :alt: Status
 .. |Python Version| image:: https://img.shields.io/pypi/pyversions/lep-downloader
    :target: https://pypi.org/project/lep-downloader
    :alt: Python Version
@@ -32,68 +37,171 @@ LEP Downloader
    :target: https://github.com/psf/black
    :alt: Black
 
+=========
 
-Features
---------
+.. badges-end
 
-* TODO
+.. raw:: html
 
+   <p align="center"><img alt="logo" src="docs/_static/logo.png" width="40%" /></p>
+   <p align="center">
+      📚
+      <a href="https://lep-downloader.readthedocs.io" target="_blank">
+         Read the full documentation
+      </a>
+      📚
+   </p>
 
-Requirements
-------------
 
-* TODO
+.. after-image
+
+About
+------
 
+LEP Downloader is a script for downloading the all FREE episodes of `Luke's ENGLISH Podcast`_.
 
-Installation
-------------
+It lets you to get all audio files (including audio tracks to video episodes)
+and also PDF files for each episode page.
+
+Even though this script was written for convenient episode downloading,
+I don't want to financially harm Luke in any way.
+I just want to make my life a bit easier (as usual for lazy IT person =).
+So consider `donating`_ to Luke's English Podcast and `becoming`_ his premium subscriber.
+And of course, subscribe on his `YouTube channel`_.
+
+
+🚀 Features
+-------------
+
+* Download a range of episodes filtering by episode number or by episode date
+* Download only the last episode
+* Download PDF files of episodes web pages
+* Saving files to specified folder on your hard / solid / flash drive
+* Running script in quiet mode for automated routine
+* Writing log file in debug mode
+
+
+🛠️ Requirements
+----------------
+
+* Python 3.8+
+* Internet connection
+
+
+💻 Installation
+----------------
 
 You can install *LEP Downloader* via pip_ from PyPI_:
 
-.. code:: console
+.. code:: none
 
-   $ pip install lep-downloader
+   pip install lep-downloader
 
+I do recommend you to use pipx_ for any CLI Python package.
+It let you install and run Python applications in isolated environments.
 
-Usage
------
+.. code:: none
 
-Please see the `Command-line Reference <Usage_>`_ for details.
+   python -m pip install --user pipx
+   pipx install lep-downloader
+   lep-downloader --help
 
 
-Contributing
-------------
+🕹 Usage
+--------
+
+.. code:: none
+
+   lep-downloader -ep 758
+
+You can also use the short script name:
+
+.. code:: none
+
+   lep-dl --last
+
+Please see the `Usage Examples <Usage_>`_ for details.
+
+Or skim the `Man Page <Manpage_>`_ for available options
+(if terminal is your best friend).
+
+
+✨ What's new in version 3
+---------------------------
+
+The third version was completely re-written by me (again).
+But this time with more fundamental and mature approach.
+I applied some OOP (object-oriented programming) principles
+and covered almost all functions with absolutely isolated unit tests.
+
+Code base became more extendable and maintainable *(I believe)*.
+I dropped support for file naming from old script versions.
+Also I removed (for awhile) video and add-ons download
+*(I plan to add them again in the future, however - no any promises)*.
+
+Archive parsing was improved (without skipping several episodes).
+Also I added built-in possibility to download files from reserve server,
+if primary link is not available (for any reason).
+
+And many internal little things.
+You can read descriptions of pre-releases on `Releases`_ page (if you wish).
+
+
+✊ Contributing
+---------------
 
 Contributions are very welcome.
 To learn more, see the `Contributor Guide`_.
 
 
-License
--------
+📝 License
+-----------
 
-Distributed under the terms of the `MIT license`_,
+Distributed under the terms of the `MIT license <https://opensource.org/licenses/MIT>`_,
 *LEP Downloader* is free and open source software.
+It means you can modify it, redistribute it or use it however you like
+as long as you do mention the author of the original script.
 
 
-Issues
-------
+🐞 Issues
+----------
 
 If you encounter any problems,
 please `file an issue`_ along with a detailed description.
 
 
-Credits
--------
+🙏🏻 Credits
+------------
 
 This project was generated from `@cjolowicz`_'s `Hypermodern Python Cookiecutter`_ template.
 
+Script uses the following packages / libraries under the hood:
+
+* `click <https://github.com/pallets/click>`_ (`BSD-3-Clause License <https://github.com/pallets/click/blob/main/LICENSE.rst>`__)
+* `requests <https://github.com/psf/requests>`_ (`Apache-2.0 License <https://github.com/psf/requests/blob/main/LICENSE>`__)
+* `beautifulsoup4 <https://www.crummy.com/software/BeautifulSoup/bs4/doc/index.html>`_ (`MIT License <https://bazaar.launchpad.net/~leonardr/beautifulsoup/bs4/view/head:/LICENSE>`__)
+* `lxml <https://github.com/lxml/lxml>`_ (`BSD-3-Clause License <https://github.com/lxml/lxml/blob/master/LICENSE.txt>`__)
+* `loguru <https://github.com/Delgan/loguru>`_ (`MIT License <https://github.com/Delgan/loguru/blob/master/LICENSE>`__)
+* `single-source <https://github.com/rabbit72/single-source>`_ (`MIT License <https://github.com/rabbit72/single-source/blob/master/LICENSE>`__)
+
+and other amazing Python packages for development and testing.
+See a full list of them in 'dependencies' section of ``pyproject.toml``
+`file <https://github.com/hotenov/LEP-downloader/blob/main/pyproject.toml>`_.
+
+.. _Luke's ENGLISH Podcast: https://teacherluke.co.uk/archive-of-episodes-1-149/
+.. _donating: https://www.paypal.com/donate/?cmd=_s-xclick&hosted_button_id=CA2KNZNBFGKC6
+.. _becoming: https://teacherluke.co.uk/premium/premiuminfo/
+.. _YouTube channel: https://www.youtube.com/c/LukesEnglishPodcast
 .. _@cjolowicz: https://github.com/cjolowicz
 .. _Cookiecutter: https://github.com/audreyr/cookiecutter
-.. _MIT license: https://opensource.org/licenses/MIT
 .. _PyPI: https://pypi.org/
 .. _Hypermodern Python Cookiecutter: https://github.com/cjolowicz/cookiecutter-hypermodern-python
 .. _file an issue: https://github.com/hotenov/lep-downloader/issues
 .. _pip: https://pip.pypa.io/
+.. _pipx: https://pipxproject.github.io/pipx/
+.. _Releases: https://github.com/hotenov/LEP-downloader/releases
+
 .. github-only
 .. _Contributor Guide: CONTRIBUTING.rst
 .. _Usage: https://lep-downloader.readthedocs.io/en/latest/usage.html
+.. _Manpage: https://lep-downloader.readthedocs.io/en/latest/manpage.html

docs/conf.py

@@ -9,7 +9,8 @@
     "sphinx.ext.autodoc",
     "sphinx.ext.napoleon",
     "sphinx_click",
-    "sphinx_rtd_theme",
 ]
 autodoc_typehints = "description"
-html_theme = "sphinx_rtd_theme"
+language = "en"
+html_logo = "_static/logo.png"
+html_theme = "furo"

docs/index.rst

@@ -1,14 +1,26 @@
+.. meta::
+   :description: LEP Downloader - Python script to download all Luke's ENGLISH Podcast
+   :keywords: python, script, download, lepsters, offline, collection
+
+.. include:: ../README.rst
+   :start-after: badges-begin
+   :end-before: badges-end
+
 .. include:: ../README.rst
+   :start-after: after-image
    :end-before: github-only
 
 .. _Contributor Guide: contributing.html
 .. _Usage: usage.html
+.. _Manpage: manpage.html
 
 .. toctree::
    :hidden:
    :maxdepth: 1
 
-   usage
+   Usage Examples <usage>
+   Man Page (--help) <manpage>
+   Why? (Motivation) <motivation>
    reference
    contributing
    Code of Conduct <codeofconduct>

docs/manpage.rst

@@ -0,0 +1,19 @@
+Man Page
+========
+
+.. important::
+   This page uses auto-generation of ``--help`` option
+   for 'download' command and script itself *(without command)*.
+
+   To download files you can use only options (without 'download' command).
+   They are the same.
+
+   If you don't know how to read and use ``--help`` output,
+   you should visit `Usage Examples`_ page (with "copy-paste" instructions)
+
+.. click:: lep_downloader.cli:cli
+   :prog: lep-downloader
+   :nested: full
+   :commands: download
+
+.. _Usage Examples: usage.html

docs/motivation.rst

@@ -0,0 +1,16 @@
+Why? (Motivation)
+=================
+
+I'm learning two languages at the moment: Python and English.
+
+And I've decided to *kill two birds with one stone*.
+
+To learn programming language is better on real project.
+For real users. Even though that user is only you.
+I was lucky - I had a broken one *(a project, not a user =)*.
+
+Developing version 3 of the script I've learned a lot of new things
+and managed to improve it significantly *(I hope so)*.
+
+In addition, the **LEP Downloader** enables us to have
+offline collection of the great podcast for English learners.

docs/reference.rst

@@ -1,13 +1,42 @@
-Reference
+Developer Reference
+===================
+
+Classes and functions definitions for main modules.
+All descriptions are generated automatically
+from source code docstrings.
+
+
+
+lep_downloader.lep
+--------------------------
+
+.. automodule:: lep_downloader.lep
+   :members:
+   :show-inheritance:
+
 =========
 
-.. contents::
-    :local:
-    :backlinks: none
+lep_downloader.downloader
+--------------------------
 
+.. automodule:: lep_downloader.downloader
+   :members:
+   :show-inheritance:
+
+=========
+
+lep_downloader.parser
+--------------------------
+
+.. automodule:: lep_downloader.parser
+   :members:
+   :show-inheritance:
+
+=========
 
-lep_downloader.cli
------------------------
+lep_downloader.exceptions
+--------------------------
 
-.. automodule:: lep_downloader.cli
+.. automodule:: lep_downloader.exceptions
    :members:
+   :show-inheritance:

docs/requirements.txt

@@ -1,3 +1,2 @@
-sphinx==4.0.2
-sphinx-click==3.0.1
-sphinx-rtd-theme==0.5.2
+sphinx==4.4.0
+sphinx-click==3.0.2