Playing with autodoc extension options

Doesn't work quite right, exploring other options for generating docs with Jesse
This commit is contained in:
Qualis Svagtlys 2023-12-19 20:44:38 -06:00
parent c61f7f60d3
commit ee717a00cb
3 changed files with 113 additions and 335 deletions

View file

@ -2,7 +2,10 @@
Entry Variables
===============
.. autoclass:: ytdl_sub.entries.script.variable_definitions.VariableDefinitions()
.. .. autoclass:: ytdl_sub.entries.script.variable_definitions.VariableDefinitions
.. :members:
.. :inherited-members:
.. :undoc-members:
.. autoclass:: ytdl_sub.entries.script.variable_definitions.VariableDefinitions
:members:
:inherited-members:
:undoc-members:

View file

@ -1,5 +1,9 @@
# Configuration file for the Sphinx documentation builder.
#
import os
import sys
sys.path.insert(0, os.path.abspath('../../src'))
# For the full list of built-in configuration values, see the documentation:
# https://www.sphinx-doc.org/en/master/usage/configuration.html
@ -17,7 +21,9 @@ release = "2023.12.15"
extensions = [
"sphinx.ext.autodoc",
"sphinx.ext.autosectionlabel",
# "sphinx.ext.autosummary",
"sphinx.ext.extlinks",
"sphinx.ext.napoleon",
"sphinx_copybutton",
"sphinx_design",
]
@ -49,6 +55,8 @@ html_theme_options = {
"announcement": (
"Migration to <a href='https://ytdl-sub--841.org.readthedocs.build/en/841/config.html#beautifying-subscriptions'>beautiful subscriptions</a> is now live"
),
"navigation_depth": 10,
"show_toc_level": 10,
}
html_static_path = ["_static"]
@ -59,3 +67,19 @@ autosectionlabel_prefix_document = True
extlinks = {"yt-dlp": ("https://github.com/yt-dlp/yt-dlp/%s", "yt-dlp%s")}
# -- Options for autodoc ----------------------------------------------------
# https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html#configuration
# Automatically extract typehints when specified and place them in
# descriptions of the relevant function/method.
autodoc_default_options = {
"autodoc_typehints_format": "short",
"autodoc_class_signature": "separated",
"add_module_names": False,
# "add_class_names": False,
}
python_use_unqualified_type_names = True
napoleon_numpy_docstring = True
napoleon_use_rtype = False

View file

@ -146,9 +146,6 @@ class VariableDefinitions:
@property
def webpage_url(self) -> MetadataVariable:
"""
Returns
-------
str
The url to the webpage.
"""
return MetadataVariable(metadata_key="webpage_url", variable_name="webpage_url")
@ -156,9 +153,6 @@ class VariableDefinitions:
@property
def info_json_ext(self) -> Variable:
"""
Returns
-------
str
The "info.json" extension
"""
return Variable("info_json_ext")
@ -166,9 +160,6 @@ class VariableDefinitions:
@property
def description(self) -> MetadataVariable:
"""
Returns
-------
str
The description if it exists. Otherwise, returns an emtpy string.
"""
return MetadataVariable(variable_name="description", metadata_key="description")
@ -176,9 +167,6 @@ class VariableDefinitions:
@property
def uploader_id(self) -> MetadataVariable:
"""
Returns
-------
str
The uploader id if it exists, otherwise return the unique ID.
"""
return MetadataVariable(variable_name="uploader_id", metadata_key="uploader_id")
@ -186,9 +174,6 @@ class VariableDefinitions:
@property
def uploader(self) -> MetadataVariable:
"""
Returns
-------
str
The uploader if it exists, otherwise return the uploader ID.
"""
return MetadataVariable(variable_name="uploader", metadata_key="uploader")
@ -196,9 +181,6 @@ class VariableDefinitions:
@property
def uploader_url(self) -> MetadataVariable:
"""
Returns
-------
str
The uploader url if it exists, otherwise returns the webpage_url.
"""
return MetadataVariable("uploader_url", metadata_key="uploader_url")
@ -206,20 +188,13 @@ class VariableDefinitions:
@property
def source_title(self) -> MetadataVariable:
"""
Returns
-------
str
Name of the source (i.e. channel with multiple playlists) if it exists, otherwise
returns its playlist_title.
Name of the source (i.e. channel with multiple playlists) if it exists, otherwise returns its playlist_title.
"""
return MetadataVariable("source_title", metadata_key=self.title.metadata_key)
@property
def source_uid(self) -> MetadataVariable:
"""
Returns
-------
str
The source unique id if it exists, otherwise returns the playlist unique ID.
"""
return MetadataVariable("source_uid", metadata_key=self.uid.metadata_key)
@ -227,22 +202,15 @@ class VariableDefinitions:
@property
def source_index(self) -> MetadataVariable:
"""
Returns
-------
int
Source index if it exists, otherwise returns ``1``.
It is recommended to not use this unless you know the source will never add new content
(it is easy for this value to change).
It is recommended to not use this unless you know the source will never add new content (it is easy for this value to change).
"""
return MetadataVariable("source_index", metadata_key=self.playlist_index.metadata_key)
@property
def source_index_padded(self) -> Variable:
"""
Returns
-------
int
The source index, padded.
"""
return Variable("source_index_padded")
@ -250,9 +218,6 @@ class VariableDefinitions:
@property
def source_count(self) -> MetadataVariable:
"""
Returns
-------
int
The source count if it exists, otherwise returns the playlist count.
"""
return MetadataVariable("source_count", metadata_key=self.playlist_count.metadata_key)
@ -260,9 +225,6 @@ class VariableDefinitions:
@property
def source_webpage_url(self) -> MetadataVariable:
"""
Returns
-------
str
The source webpage url if it exists, otherwise returns the playlist webpage url.
"""
return MetadataVariable("source_webpage_url", metadata_key=self.webpage_url.metadata_key)
@ -270,9 +232,6 @@ class VariableDefinitions:
@property
def source_description(self) -> MetadataVariable:
"""
Returns
-------
str
The source description if it exists, otherwise returns the playlist description.
"""
return MetadataVariable("source_description", metadata_key=self.description.metadata_key)
@ -280,9 +239,6 @@ class VariableDefinitions:
@property
def playlist_uid(self) -> MetadataVariable:
"""
Returns
-------
str
The playlist unique ID if it exists, otherwise return the entry unique ID.
"""
return MetadataVariable(variable_name="playlist_uid", metadata_key="playlist_id")
@ -290,9 +246,6 @@ class VariableDefinitions:
@property
def playlist_title(self) -> MetadataVariable:
"""
Returns
-------
str
Name of its parent playlist/channel if it exists, otherwise returns its title.
"""
return MetadataVariable(variable_name="playlist_title", metadata_key="playlist_title")
@ -300,22 +253,15 @@ class VariableDefinitions:
@property
def playlist_index(self) -> MetadataVariable:
"""
Returns
-------
int
Playlist index if it exists, otherwise returns ``1``.
Note that for channels/playlists, any change (i.e. adding or removing a video) will make
this value change. Use with caution.
Note that for channels/playlists, any change (i.e. adding or removing a video) will make this value change. Use with caution.
"""
return MetadataVariable(metadata_key="playlist_index", variable_name="playlist_index")
@property
def playlist_index_reversed(self) -> Variable:
"""
Returns
-------
int
Playlist index reversed via ``playlist_count - playlist_index + 1``
"""
return Variable("playlist_index_reversed")
@ -323,9 +269,6 @@ class VariableDefinitions:
@property
def playlist_index_padded(self) -> Variable:
"""
Returns
-------
str
playlist_index padded two digits
"""
return Variable("playlist_index_padded")
@ -333,9 +276,6 @@ class VariableDefinitions:
@property
def playlist_index_reversed_padded(self) -> Variable:
"""
Returns
-------
str
playlist_index_reversed padded two digits
"""
return Variable("playlist_index_reversed_padded")
@ -343,9 +283,6 @@ class VariableDefinitions:
@property
def playlist_index_padded6(self) -> Variable:
"""
Returns
-------
str
playlist_index padded six digits.
"""
return Variable("playlist_index_padded6")
@ -353,9 +290,6 @@ class VariableDefinitions:
@property
def playlist_index_reversed_padded6(self) -> Variable:
"""
Returns
-------
str
playlist_index_reversed padded six digits.
"""
return Variable("playlist_index_reversed_padded6")
@ -363,22 +297,15 @@ class VariableDefinitions:
@property
def playlist_count(self) -> MetadataVariable:
"""
Returns
-------
int
Playlist count if it exists, otherwise returns ``1``.
Note that for channels/playlists, any change (i.e. adding or removing a video) will make
this value change. Use with caution.
Note that for channels/playlists, any change (i.e. adding or removing a video) will make this value change. Use with caution.
"""
return MetadataVariable(variable_name="playlist_count", metadata_key="playlist_count")
@property
def playlist_description(self) -> MetadataVariable:
"""
Returns
-------
str
The playlist description if it exists, otherwise returns the entry's description.
"""
return MetadataVariable(
@ -388,9 +315,6 @@ class VariableDefinitions:
@property
def playlist_webpage_url(self) -> MetadataVariable:
"""
Returns
-------
str
The playlist webpage url if it exists. Otherwise, returns the entry webpage url.
"""
return MetadataVariable(
@ -400,21 +324,14 @@ class VariableDefinitions:
@property
def playlist_max_upload_date(self) -> Variable:
"""
Returns
-------
Max upload_date for all entries in this entry's playlist if it exists, otherwise returns
``upload_date``
Max upload_date for all entries in this entry's playlist if it exists, otherwise returns ``upload_date``
"""
return Variable("playlist_max_upload_date")
@property
def playlist_max_upload_year(self) -> Variable:
"""
Returns
-------
int
Max upload_year for all entries in this entry's playlist if it exists, otherwise returns
``upload_year``
Max upload_year for all entries in this entry's playlist if it exists, otherwise returns ``upload_year``
"""
# override in EntryParent
return Variable("playlist_max_upload_year")
@ -422,20 +339,13 @@ class VariableDefinitions:
@property
def playlist_max_upload_year_truncated(self) -> Variable:
"""
Returns
-------
int
The max playlist truncated upload year for all entries in this entry's playlist if it
exists, otherwise returns ``upload_year_truncated``.
The max playlist truncated upload year for all entries in this entry's playlist if it exists, otherwise returns ``upload_year_truncated``.
"""
return Variable("playlist_max_upload_year_truncated")
@property
def playlist_uploader_id(self) -> MetadataVariable:
"""
Returns
-------
str
The playlist uploader id if it exists, otherwise returns the entry uploader ID.
"""
return MetadataVariable("playlist_uploader_id", metadata_key="playlist_uploader_id")
@ -443,9 +353,6 @@ class VariableDefinitions:
@property
def playlist_uploader(self) -> MetadataVariable:
"""
Returns
-------
str
The playlist uploader if it exists, otherwise return the entry uploader.
"""
return MetadataVariable("playlist_uploader", metadata_key=self.uploader.metadata_key)
@ -453,9 +360,6 @@ class VariableDefinitions:
@property
def playlist_uploader_url(self) -> MetadataVariable:
"""
Returns
-------
str
The playlist uploader url if it exists, otherwise returns the playlist webpage_url.
"""
return MetadataVariable(
@ -465,9 +369,6 @@ class VariableDefinitions:
@property
def source_uploader_id(self) -> MetadataVariable:
"""
Returns
-------
str
The source uploader id if it exists, otherwise returns the playlist_uploader_id
"""
return MetadataVariable("source_uploader_id", metadata_key=self.uploader_id.metadata_key)
@ -475,9 +376,6 @@ class VariableDefinitions:
@property
def source_uploader(self) -> MetadataVariable:
"""
Returns
-------
str
The source uploader if it exists, otherwise return the playlist_uploader
"""
return MetadataVariable("source_uploader", metadata_key=self.uploader.metadata_key)
@ -485,9 +383,6 @@ class VariableDefinitions:
@property
def source_uploader_url(self) -> MetadataVariable:
"""
Returns
-------
str
The source uploader url if it exists, otherwise returns the source webpage_url.
"""
return MetadataVariable("source_uploader_url", metadata_key=self.uploader_url.metadata_key)
@ -495,9 +390,6 @@ class VariableDefinitions:
@property
def creator(self) -> MetadataVariable:
"""
Returns
-------
str
The creator name if it exists, otherwise returns the channel.
"""
return MetadataVariable(variable_name="creator", metadata_key="creator")
@ -505,9 +397,6 @@ class VariableDefinitions:
@property
def channel(self) -> MetadataVariable:
"""
Returns
-------
str
The channel name if it exists, otherwise returns the uploader.
"""
return MetadataVariable(variable_name="channel", metadata_key="channel")
@ -515,9 +404,6 @@ class VariableDefinitions:
@property
def channel_id(self) -> MetadataVariable:
"""
Returns
-------
str
The channel id if it exists, otherwise returns the entry uploader ID.
"""
return MetadataVariable(variable_name="channel_id", metadata_key="channel_id")
@ -525,9 +411,6 @@ class VariableDefinitions:
@property
def ext(self) -> MetadataVariable:
"""
Returns
-------
str
The downloaded entry's file extension
"""
return MetadataVariable(variable_name="ext", metadata_key="ext")
@ -535,11 +418,7 @@ class VariableDefinitions:
@property
def thumbnail_ext(self) -> Variable:
"""
Returns
-------
str
The download entry's thumbnail extension. Will always return 'jpg'. Until there is a
need to support other image types, we always convert to jpg.
The download entry's thumbnail extension. Will always return 'jpg'. Until there is a need to support other image types, we always convert to jpg.
"""
return Variable("thumbnail_ext")
@ -581,20 +460,13 @@ class VariableDefinitions:
@property
def download_index(self) -> Variable:
"""
Returns
-------
int
The i'th entry downloaded. NOTE that this is fetched dynamically from the download
archive.
The i'th entry downloaded. NOTE that this is fetched dynamically from the download archive.
"""
return Variable(variable_name="download_index")
@property
def download_index_padded6(self) -> Variable:
"""
Returns
-------
str
The download_index padded six digits
"""
return Variable("download_index_padded6")
@ -602,9 +474,6 @@ class VariableDefinitions:
@property
def upload_date_index(self) -> Variable:
"""
Returns
-------
int
The i'th entry downloaded with this upload date.
"""
return Variable(variable_name="upload_date_index")
@ -612,9 +481,6 @@ class VariableDefinitions:
@property
def upload_date_index_padded(self) -> Variable:
"""
Returns
-------
int
The upload_date_index padded two digits
"""
return Variable("upload_date_index_padded")
@ -622,9 +488,6 @@ class VariableDefinitions:
@property
def upload_date_index_reversed(self) -> Variable:
"""
Returns
-------
int
100 - upload_date_index
"""
return Variable("upload_date_index_reversed")
@ -632,9 +495,6 @@ class VariableDefinitions:
@property
def upload_date_index_reversed_padded(self) -> Variable:
"""
Returns
-------
int
The upload_date_index padded two digits
"""
return Variable("upload_date_index_reversed_padded")
@ -642,19 +502,13 @@ class VariableDefinitions:
@property
def upload_date(self) -> MetadataVariable:
"""
Returns
-------
str
The entrys uploaded date, in YYYYMMDD format. If not present, return todays date.
The entry's uploaded date, in YYYYMMDD format. If not present, return today's date.
"""
return MetadataVariable(variable_name="upload_date", metadata_key="upload_date")
@property
def upload_year(self) -> Variable:
"""
Returns
-------
int
The entry's upload year
"""
return Variable("upload_year")
@ -662,9 +516,6 @@ class VariableDefinitions:
@property
def upload_year_truncated(self) -> Variable:
"""
Returns
-------
int
The last two digits of the upload year, i.e. 22 in 2022
"""
return Variable("upload_year_truncated")
@ -672,20 +523,13 @@ class VariableDefinitions:
@property
def upload_year_truncated_reversed(self) -> Variable:
"""
Returns
-------
int
The upload year truncated, but reversed using ``100 - {upload_year_truncated}``, i.e.
2022 returns ``100 - 22`` = ``78``
The upload year truncated, but reversed using ``100 - {upload_year_truncated}``, i.e. 2022 returns ``100 - 22`` = ``78``
"""
return Variable("upload_year_truncated_reversed")
@property
def upload_month_reversed(self) -> Variable:
"""
Returns
-------
int
The upload month, but reversed using ``13 - {upload_month}``, i.e. March returns ``10``
"""
return Variable("upload_month_reversed")
@ -693,9 +537,6 @@ class VariableDefinitions:
@property
def upload_month_reversed_padded(self) -> Variable:
"""
Returns
-------
str
The reversed upload month, but padded. i.e. November returns "02"
"""
return Variable("upload_month_reversed_padded")
@ -703,9 +544,6 @@ class VariableDefinitions:
@property
def upload_month_padded(self) -> Variable:
"""
Returns
-------
str
The entry's upload month padded to two digits, i.e. March returns "03"
"""
return Variable("upload_month_padded")
@ -713,9 +551,6 @@ class VariableDefinitions:
@property
def upload_day_padded(self) -> Variable:
"""
Returns
-------
str
The entry's upload day padded to two digits, i.e. the fifth returns "05"
"""
return Variable("upload_day_padded")
@ -723,9 +558,6 @@ class VariableDefinitions:
@property
def upload_month(self) -> Variable:
"""
Returns
-------
int
The upload month as an integer (no padding).
"""
return Variable("upload_month")
@ -733,9 +565,6 @@ class VariableDefinitions:
@property
def upload_day(self) -> Variable:
"""
Returns
-------
int
The upload day as an integer (no padding).
"""
return Variable("upload_day")
@ -743,20 +572,13 @@ class VariableDefinitions:
@property
def upload_day_reversed(self) -> Variable:
"""
Returns
-------
int
The upload day, but reversed using ``{total_days_in_month} + 1 - {upload_day}``,
i.e. August 8th would have upload_day_reversed of ``31 + 1 - 8`` = ``24``
The upload day, but reversed using ``{total_days_in_month} + 1 - {upload_day}``, i.e. August 8th would have upload_day_reversed of ``31 + 1 - 8`` = ``24``
"""
return Variable("upload_day_reversed")
@property
def upload_day_reversed_padded(self) -> Variable:
"""
Returns
-------
str
The reversed upload day, but padded. i.e. August 30th returns "02".
"""
return Variable("upload_day_reversed_padded")
@ -764,9 +586,6 @@ class VariableDefinitions:
@property
def upload_day_of_year(self) -> Variable:
"""
Returns
-------
int
The day of the year, i.e. February 1st returns ``32``
"""
return Variable("upload_day_of_year")
@ -774,9 +593,6 @@ class VariableDefinitions:
@property
def upload_day_of_year_padded(self) -> Variable:
"""
Returns
-------
str
The upload day of year, but padded i.e. February 1st returns "032"
"""
return Variable("upload_day_of_year_padded")
@ -784,20 +600,13 @@ class VariableDefinitions:
@property
def upload_day_of_year_reversed(self) -> Variable:
"""
Returns
-------
int
The upload day, but reversed using ``{total_days_in_year} + 1 - {upload_day}``,
i.e. February 2nd would have upload_day_of_year_reversed of ``365 + 1 - 32`` = ``334``
The upload day, but reversed using ``{total_days_in_year} + 1 - {upload_day}``, i.e. February 2nd would have upload_day_of_year_reversed of ``365 + 1 - 32`` = ``334``
"""
return Variable("upload_day_of_year_reversed")
@property
def upload_day_of_year_reversed_padded(self) -> Variable:
"""
Returns
-------
str
The reversed upload day of year, but padded i.e. December 31st returns "001"
"""
return Variable("upload_day_of_year_reversed_padded")
@ -805,9 +614,6 @@ class VariableDefinitions:
@property
def upload_date_standardized(self) -> Variable:
"""
Returns
-------
str
The uploaded date formatted as YYYY-MM-DD
"""
return Variable("upload_date_standardized")
@ -815,19 +621,13 @@ class VariableDefinitions:
@property
def release_date(self) -> MetadataVariable:
"""
Returns
-------
str
The entrys release date, in YYYYMMDD format. If not present, return the upload date.
The entry's release date, in YYYYMMDD format. If not present, return the upload date.
"""
return MetadataVariable(variable_name="release_date", metadata_key="release_date")
@property
def release_year(self) -> Variable:
"""
Returns
-------
int
The entry's release year
"""
return Variable("release_year")
@ -835,9 +635,6 @@ class VariableDefinitions:
@property
def release_year_truncated(self) -> Variable:
"""
Returns
-------
int
The last two digits of the release year, i.e. 22 in 2022
"""
return Variable("release_year_truncated")
@ -845,31 +642,20 @@ class VariableDefinitions:
@property
def release_year_truncated_reversed(self) -> Variable:
"""
Returns
-------
int
The release year truncated, but reversed using ``100 - {release_year_truncated}``, i.e.
2022 returns ``100 - 22`` = ``78``
The release year truncated, but reversed using ``100 - {release_year_truncated}``, i.e. 2022 returns ``100 - 22`` = ``78``
"""
return Variable("release_year_truncated_reversed")
@property
def release_month_reversed(self) -> Variable:
"""
Returns
-------
int
The release month, but reversed
using ``13 - {release_month}``, i.e. March returns ``10``
The release month, but reversed using ``13 - {release_month}``, i.e. March returns ``10``
"""
return Variable("release_month_reversed")
@property
def release_month_reversed_padded(self) -> Variable:
"""
Returns
-------
str
The reversed release month, but padded. i.e. November returns "02"
"""
return Variable("release_month_reversed_padded")
@ -877,9 +663,6 @@ class VariableDefinitions:
@property
def release_month_padded(self) -> Variable:
"""
Returns
-------
str
The entry's release month padded to two digits, i.e. March returns "03"
"""
return Variable("release_month_padded")
@ -887,9 +670,6 @@ class VariableDefinitions:
@property
def release_day_padded(self) -> Variable:
"""
Returns
-------
str
The entry's release day padded to two digits, i.e. the fifth returns "05"
"""
return Variable("release_day_padded")
@ -897,9 +677,6 @@ class VariableDefinitions:
@property
def release_month(self) -> Variable:
"""
Returns
-------
int
The release month as an integer (no padding).
"""
return Variable("release_month")
@ -907,9 +684,6 @@ class VariableDefinitions:
@property
def release_day(self) -> Variable:
"""
Returns
-------
int
The release day as an integer (no padding).
"""
return Variable("release_day")
@ -917,20 +691,13 @@ class VariableDefinitions:
@property
def release_day_reversed(self) -> Variable:
"""
Returns
-------
int
The release day, but reversed using ``{total_days_in_month} + 1 - {release_day}``,
i.e. August 8th would have release_day_reversed of ``31 + 1 - 8`` = ``24``
The release day, but reversed using ``{total_days_in_month} + 1 - {release_day}``, i.e. August 8th would have release_day_reversed of ``31 + 1 - 8`` = ``24``
"""
return Variable("release_day_reversed")
@property
def release_day_reversed_padded(self) -> Variable:
"""
Returns
-------
str
The reversed release day, but padded. i.e. August 30th returns "02".
"""
return Variable("release_day_reversed_padded")
@ -938,9 +705,6 @@ class VariableDefinitions:
@property
def release_day_of_year(self) -> Variable:
"""
Returns
-------
int
The day of the year, i.e. February 1st returns ``32``
"""
return Variable("release_day_of_year")
@ -948,9 +712,6 @@ class VariableDefinitions:
@property
def release_day_of_year_padded(self) -> Variable:
"""
Returns
-------
str
The release day of year, but padded i.e. February 1st returns "032"
"""
return Variable("release_day_of_year_padded")
@ -958,20 +719,13 @@ class VariableDefinitions:
@property
def release_day_of_year_reversed(self) -> Variable:
"""
Returns
-------
int
The release day, but reversed using ``{total_days_in_year} + 1 - {release_day}``,
i.e. February 2nd would have release_day_of_year_reversed of ``365 + 1 - 32`` = ``334``
The release day, but reversed using ``{total_days_in_year} + 1 - {release_day}``, i.e. February 2nd would have release_day_of_year_reversed of ``365 + 1 - 32`` = ``334``
"""
return Variable("release_day_of_year_reversed")
@property
def release_day_of_year_reversed_padded(self) -> Variable:
"""
Returns
-------
str
The reversed release day of year, but padded i.e. December 31st returns "001"
"""
return Variable("release_day_of_year_reversed_padded")
@ -979,9 +733,6 @@ class VariableDefinitions:
@property
def release_date_standardized(self) -> Variable:
"""
Returns
-------
str
The release date formatted as YYYY-MM-DD
"""
return Variable("release_date_standardized")