[DOCS] Complete overhaul of readthedocs #847

Svagtlys · 2023-12-19T18:29:05Z

This is an ongoing project to revamp the YTDL-Sub docs. Starting point:

Recreate docs folder/file structure
Update root makefile to use new make docs command
Move old docs into new docs folder structure (as a base)
Separate out old docs into individual files to allow better navigation with the new theme

Initial plans:

step-by-step layman install instructions for each platform
pages for each pre-built preset, showing which variables can be overridden to do different things (i.e. episode_title)
new wiki walkthrough that uses the README config as a starting point, and gradually adds custom changes
pages for how to enable custom metadata agents for Kodi/Plex/jellyfin
page dedicated to explaining the structure of a config (it's only lightly touched on now, many folks struggle to understand the 'pattern' of presets/plugins/overrides)

This is an ongoing project to revamp the YTDL-Sub docs. Starting point: - Recreate docs folder/file structure - Update root makefile to use new make docs command - Move old docs into new docs folder structure (as a base) - Separate out old docs into individual files to allow better navigation with the new theme

codecov · 2023-12-19T18:44:26Z

Codecov Report

All modified and coverable lines are covered by tests ✅

Comparison is base (b8fb119) 96.99% compared to head (4fe8bed) 96.99%.
Report is 1 commits behind head on master.

Additional details and impacted files

@@           Coverage Diff           @@
##           master     #847   +/-   ##
=======================================
  Coverage   96.99%   96.99%           
=======================================
  Files         116      116           
  Lines        7115     7116    +1     
=======================================
+ Hits         6901     6902    +1     
  Misses        214      214

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

Also some minor accessibility updates (alt text on intro images)

jmbannon · 2023-12-19T23:18:47Z

docs/source/guides/getting_started/first_config.rst

+Your first configuration will look pretty simple:
+
+.. code-block:: yaml
+    :linenos:


jmbannon · 2023-12-19T23:19:11Z

docs/source/guides/getting_started/first_config.rst

+.. code-block:: yaml
+    :linenos:
+
+    configuration:


Let's make indents 2, that has been the historical value to use in all codedocs

jmbannon · 2023-12-19T23:20:27Z

docs/source/guides/getting_started/index.rst

+
+Now that you have installed ``ytdl-sub``, checked your skills, and gotten a bit of background on how ``ytdl-sub`` functions, read through the articles below to get started:
+
+:doc:`Step 1: Initial Configuration <first_config>`


I think we should have a step prior to this that explains on how to just use the subscription before jumping into config building

jmbannon · 2023-12-19T23:22:13Z

docs/source/guides/getting_started/first_config.rst

+
+Line 4 begins the definition o your custom ``presets``, with line 5 being the name of your first custom ``preset``.
+
+Lines 7 and 8 tell ``ytdl-sub`` which :doc:`/guides/getting_started/prebuilt_presets` to expand on; these ``presets`` already indicate that the downloaded files should be: 


In the docs, its noted as Example Configs when it should be Prebuilt Presets

jmbannon · 2023-12-19T23:22:41Z

docs/source/guides/getting_started/first_config.rst

+The first two lines in this ``config.yaml`` file are the ``configuration``, and define the ``working_directory``, which is described near the bottom of :ref:`this section <guides/getting_started/index:quick overview of \`\`ytdl-sub\`\`>`
+
+
+Line 4 begins the definition o your custom ``presets``, with line 5 being the name of your first custom ``preset``.


type: o -> of

jmbannon · 2023-12-19T23:23:41Z

docs/source/guides/getting_started/first_sub.rst

+
+The first line in this subscription file is the ``preset``, which provides the "definitions" for the subscription as listed in :doc:`/guides/getting_started/first_config`.
+
+The second line is the actual ``subscription``, named ``Rick Astley``, with a link to a :yt-dlp:`yt-dlp supported site <blob/master/supportedsites.md>`, in this case a YouTube channel.


Should probably mention somewhere that __preset__ values now live in the config itself

jmbannon · 2023-12-19T23:24:29Z

docs/source/guides/getting_started/first_sub.rst

+Initial Subscription
+====================
+
+Your first subscription should look similar to the below:


Should mention something like "Using our config built in , your first subscription..."

jmbannon · 2023-12-19T23:26:36Z

docs/source/guides/getting_started/automating_downloads.rst

+
+.. tab-set::
+
+    .. tab-item:: GUI Image


jmbannon · 2023-12-19T23:27:44Z

docs/source/guides/getting_started/index.rst

+
+:doc:`Step 4: Automating Downloads <automating_downloads>`
+
+:doc:`Advanced Configuration <advanced_configuration>`


This should live before Initial Configuration IMO to lay the groundwork of what a config.yaml looks like

jmbannon · 2023-12-19T23:29:28Z

docs/source/code_reference/entry_variables.rst

+Entry Variables
+===============
+
+.. autoclass:: ytdl_sub.entries.script.variable_definitions.VariableDefinitions()


I need to poke around and figure out how to get each property (variable) to show on the right-hand side - this page not very helpful otherwise

jmbannon · 2023-12-20T00:51:44Z

docs/source/conf.py

+        },
+    ],
+    "announcement": (
+        "Migration to <a href='https://ytdl-sub--841.org.readthedocs.build/en/841/config.html#beautifying-subscriptions'>beautiful subscriptions</a> is now live"


Let's make this say that docs are heavily WIP

Doesn't work quite right, exploring other options for generating docs with Jesse

Svagtlys · 2023-12-24T16:26:07Z

Ready for review to allow for parallel work

jmbannon · 2023-12-24T17:47:43Z

docs/source/index.rst

+  faq/index
+  deprecation_notices
+
+.. note:: End goal similar to: https://picard-docs.musicbrainz.org/en/functions/list_by_type.html


Let's remove this

Or better yet make like a two sentence statement about how the docs are an active WIP

Svagtlys added 10 commits December 16, 2023 19:17

Moving cron setup and intro to ytdl-sub from GH

a297526

Getting RTD mockup on GH to work

5de741e

Try again

cdd7060

Take 3

1e27e7a

Migrating GH walkthrough to rtd

4499ed8

Create advanced config page

92d318b

Merge branch 'master' into fixed-merge

d70d38e

Create advanced config page

1579d44

Svagtlys mentioned this pull request Dec 19, 2023

Documentation Overhaul #841

Closed

Splitting config.rst

c61f7f6

Also some minor accessibility updates (alt text on intro images)

jmbannon reviewed Dec 19, 2023

View reviewed changes

docs/source/guides/getting_started/automating_downloads.rst Outdated

.. tab-set::

.. tab-item:: GUI Image

Copy link

Owner

jmbannon Dec 19, 2023

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Amazing!

jmbannon reviewed Dec 19, 2023

View reviewed changes

jmbannon reviewed Dec 20, 2023

View reviewed changes

Svagtlys added 2 commits December 19, 2023 20:44

Playing with autodoc extension options

ee717a0

Doesn't work quite right, exploring other options for generating docs with Jesse

Correct indentation (4 -> 2)

6444897

Svagtlys force-pushed the doc-revamp branch from 44d6eb3 to 6444897 Compare December 20, 2023 19:32

Svagtlys added 3 commits December 20, 2023 13:38

Merge remote-tracking branch 'origin/master' into doc-revamp

5773a73

undo changes to variable_definitions

ed0a695

Add in generated docs, documenting prebuilt_presets

c7b25d2

Svagtlys added 11 commits December 21, 2023 11:44

Update agnostic install page with more info

7335a4f

Playing around with adding a margin note to the Install index page

0f29e68

Better docker install docs

279e425

Reformatted linux install page

5eae7c7

Slight updates to unraid install instruction page

df15477

Pre-publish changes

ef67d61

Working on layman preset explanation

c32b029

test commit

81b1bb7

test 2

e96289e

Literal include of prebuilt preset files, proof of concept

e3c4f96

Presets and touch ups

8a8dce0

Svagtlys marked this pull request as ready for review December 24, 2023 16:24

Linting

Loading
Loading status checks…

4fe8bed

jmbannon reviewed Dec 24, 2023

View reviewed changes

jmbannon changed the title ~~Doc revamp~~ [DOCS] Complete overhaul of readthedocs Dec 26, 2023

jmbannon merged commit 008bcf1 into jmbannon:master Dec 27, 2023

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[DOCS] Complete overhaul of readthedocs #847

[DOCS] Complete overhaul of readthedocs #847

Svagtlys commented Dec 19, 2023

codecov bot commented Dec 19, 2023 •

edited

Loading

jmbannon Dec 19, 2023

jmbannon Dec 19, 2023

jmbannon Dec 19, 2023

jmbannon Dec 19, 2023

jmbannon Dec 19, 2023

jmbannon Dec 19, 2023

jmbannon Dec 19, 2023

jmbannon Dec 19, 2023

jmbannon Dec 19, 2023

jmbannon Dec 19, 2023

jmbannon Dec 20, 2023

Svagtlys commented Dec 24, 2023

jmbannon Dec 24, 2023

jmbannon Dec 24, 2023


		Now that you have installed ``ytdl-sub``, checked your skills, and gotten a bit of background on how ``ytdl-sub`` functions, read through the articles below to get started:

		:doc:`Step 1: Initial Configuration <first_config>`


		Line 4 begins the definition o your custom ``presets``, with line 5 being the name of your first custom ``preset``.

		Lines 7 and 8 tell ``ytdl-sub`` which :doc:`/guides/getting_started/prebuilt_presets` to expand on; these ``presets`` already indicate that the downloaded files should be:

		The first two lines in this ``config.yaml`` file are the ``configuration``, and define the ``working_directory``, which is described near the bottom of :ref:`this section <guides/getting_started/index:quick overview of \`\`ytdl-sub\`\`>`


		Line 4 begins the definition o your custom ``presets``, with line 5 being the name of your first custom ``preset``.


		The first line in this subscription file is the ``preset``, which provides the "definitions" for the subscription as listed in :doc:`/guides/getting_started/first_config`.

		The second line is the actual ``subscription``, named ``Rick Astley``, with a link to a :yt-dlp:`yt-dlp supported site <blob/master/supportedsites.md>`, in this case a YouTube channel.


		:doc:`Step 4: Automating Downloads <automating_downloads>`

		:doc:`Advanced Configuration <advanced_configuration>`

[DOCS] Complete overhaul of readthedocs #847

[DOCS] Complete overhaul of readthedocs #847

Conversation

Svagtlys commented Dec 19, 2023

codecov bot commented Dec 19, 2023 • edited Loading

Codecov Report

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Svagtlys commented Dec 24, 2023

Choose a reason for hiding this comment

Choose a reason for hiding this comment

codecov bot commented Dec 19, 2023 •

edited

Loading