Skip to content

Commit b34cfb2

Browse files
aninhasalespaninhasalesp
committed
implementing read the docs config
1 parent c6b4e14 commit b34cfb2

File tree

8 files changed

+622
-1
lines changed

8 files changed

+622
-1
lines changed

‎CONTRIBUTING.rst‎

Lines changed: 120 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,120 @@
1+
How to contribute to Youtool
2+
============================
3+
4+
Thank you for considering to Youtool!
5+
6+
First time setup in your local environment:
7+
-------------------------------------------
8+
9+
- Make sure you have a `GitHub account <https://github.com/>`_
10+
11+
- Fork Youtool to your GitHub account by clicking the `Fork <https://github.com/PythonicCafe/youtool/fork>`_ button
12+
13+
- `Clone <https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/fork-a-repo#step-2-create-a-local-clone-of-your-fork>`_ your fork locally, replacing your-username in the command below with your actual username
14+
15+
.. code-block::
16+
17+
git clone https://github.com/your-username/youtool
18+
cd youtool
19+
20+
Installation Poetry
21+
-------------------
22+
To manage dependencies and packaging for the project, we use Poetry.
23+
- Please follow the installation instructions provided in the `poetry <https://python-poetry.org/docs/#installation>`_
24+
25+
26+
Setting Up the Virtual Environment
27+
----------------------------------
28+
- After installing Poetry, you need to set up the virtual environment for the project. Navigate to the project directory and run the following command:
29+
30+
.. code-block::
31+
32+
poetry shell
33+
34+
This command will create and activate a virtual environment for the project.
35+
36+
37+
Installing Dependencies
38+
-----------------------
39+
- Once the virtual environment is activated, you can install the project dependencies by running:
40+
41+
.. code-block::
42+
43+
poetry install
44+
45+
This command will install all the dependencies listed in the pyproject.toml file.
46+
47+
48+
Creating a Local Branch from a Remote Branch
49+
--------------------------------------------
50+
To start contributing, you need to create a local branch based on a remote branch.
51+
Use the following commands to achieve this:
52+
1. Fetch the latest changes from the remote repository:
53+
54+
.. code-block::
55+
56+
git fetch origin
57+
58+
2. Create and switch to a new branch based on the remote branch:
59+
60+
.. code-block::
61+
62+
git checkout -b <new-branch-name> origin/<remote-branch-name>
63+
64+
Push your commits to your fork on GitHub and `create a pull request <https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request>`_. Link to the issue being addressed with fixes #123 in the pull request description.
65+
66+
.. code-block::
67+
68+
git push --set-upstream origin nome-do-seu-branch
69+
70+
Replace <new-branch-name> with your desired branch name and <remote-branch-name> with the name of the remote branch you want to base your work on.
71+
72+
By following these steps, you'll have a local branch set up and ready for your contributions.
73+
74+
75+
Running Tests
76+
-------------
77+
Before submitting your changes, it's important to run the tests to ensure everything is working correctly.
78+
Depending on whether you are inside or outside the virtual environment, use one of the following commands:
79+
80+
1. Inside the virtual environment:
81+
If you have already activated the virtual environment with poetry shell, run:
82+
83+
.. code-block::
84+
85+
pytest
86+
87+
2. Outside the virtual environment:
88+
If you are not inside the virtual environment, you can still run the tests using Poetry:
89+
90+
.. code-block::
91+
92+
poetry run pytest
93+
94+
By following these steps, you'll ensure that all tests are run correctly before submitting your contributions.
95+
96+
Updating Documentation
97+
----------------------
98+
Our documentation is hosted on Read the Docs, and the configuration files are located in the docs directory. To update the documentation, follow these steps:
99+
100+
1. Navigate to the docs directory:
101+
102+
.. code-block::
103+
104+
cd docs
105+
106+
2. Make your changes:
107+
Edit the necessary files to update the documentation.
108+
The main configuration file is typically conf.py, but you may also need to update other ``.rst`` files as required.
109+
110+
3. Build the documentation locally:
111+
After making your changes, you can build the HTML version of the documentation to preview your updates.
112+
Run the following command:
113+
114+
.. code-block::
115+
116+
make html
117+
118+
Open ``_build/html/index.html`` in your browser to view the docs.
119+
120+
Read more about `Sphinx <https://www.sphinx-doc.org/en/master/>`_.

‎docs/Makefile‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
# Minimal makefile for Sphinx documentation
2+
#
3+
4+
# You can set these variables from the command line, and also
5+
# from the environment for the first two.
6+
SPHINXOPTS ?=
7+
SPHINXBUILD ?= sphinx-build
8+
SOURCEDIR = .
9+
BUILDDIR = _build
10+
11+
# Put it first so that "make" without argument is like "make help".
12+
help:
13+
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
14+
15+
.PHONY: help Makefile
16+
17+
# Catch-all target: route all unknown targets to Sphinx using the new
18+
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
19+
%: Makefile
20+
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

‎docs/conf.py‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
# Configuration file for the Sphinx documentation builder.
2+
#
3+
# For the full list of built-in configuration values, see the documentation:
4+
# https://www.sphinx-doc.org/en/master/usage/configuration.html
5+
6+
# -- Project information -----------------------------------------------------
7+
# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
8+
9+
project = 'Youtool'
10+
copyright = '2024, Álvaro Justen'
11+
author = 'Álvaro Justen'
12+
13+
# -- General configuration ---------------------------------------------------
14+
# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
15+
16+
extensions = ["myst_parser"]
17+
18+
templates_path = ['_templates']
19+
exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
20+
21+
22+
23+
# -- Options for HTML output -------------------------------------------------
24+
# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
25+
26+
html_theme = 'alabaster'
27+
html_static_path = ['_static']

‎docs/contributing.rst‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
.. include:: ../CONTRIBUTING.rst

‎docs/index.rst‎

Lines changed: 156 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,156 @@
1+
.. youtool documentation master file, created by
2+
sphinx-quickstart on Mon Jul 8 14:31:22 2024.
3+
You can adapt this file completely to your liking, but it should at least
4+
contain the root `toctree` directive.
5+
6+
Welcome to youtool documentation!
7+
=================================
8+
9+
Easily access YouTube Data API v3 in batches
10+
--------------------------------------------
11+
12+
.. toctree::
13+
:maxdepth: 2
14+
15+
contributing
16+
17+
--------------------------------------------
18+
19+
Python library and command-line interface to crawl YouTube Data API v3 in batch operations and other related tasks.
20+
Easier to use than alternatives - you don't need to spend time learning the YouTube API and its caveats.
21+
With this library you can get:
22+
23+
- Channel ID from channel URL (scraping) or username (API)
24+
- Channel information (title, subscribers etc.)
25+
- List of playlists for a channel
26+
- List of videos for a playlist
27+
- Video information (title, description, likes, comments etc.)
28+
- Comments
29+
- Livechat, including superchat (scraping using chat-downloader)
30+
- Automatic transcription (scraping using yt-dlp)
31+
32+
The library will automatically:
33+
34+
- Try as many keys as you provide
35+
- Use batch of 50 items in supported API endpoints
36+
- Paginate when needed
37+
38+
Installation
39+
------------
40+
41+
Install project by running
42+
43+
.. code-block:: python
44+
45+
pip install youtool
46+
47+
Using as a library
48+
------------------
49+
Just follow the tutorial/examples below and check the ``help()`` for ``YouTube`` methods.
50+
51+
`GitHub Repository <https://github.com/PythonicCafe/youtool?tab=readme-ov-file#using-as-a-library:~:text=Using%20as%20a-,library,-Just%20follow%20the>`_
52+
53+
1. Initializing the YouTube API:
54+
55+
.. code-block:: python
56+
57+
from youtool import YouTube
58+
59+
api_keys = ["key1", "key2", ...]
60+
yt = YouTube(api_keys, disable_ipv6=True)
61+
62+
Here, we are creating an instance of the YouTube class using a list of YouTube API keys.
63+
The disable_ipv6=True option is passed to disable IPv6 usage.
64+
65+
2. Extracting Channel IDs by url:
66+
67+
.. code-block:: python
68+
69+
channel_id_1 = yt.channel_id_from_url("https://youtube.com/c/PythonicCafe/")
70+
print(f"Pythonic Café's channel ID (got from URL): {channel_id_1}")
71+
72+
3. Extracting Channel IDs by username:
73+
74+
.. code-block:: python
75+
76+
channel_id_2 = yt.channel_id_from_username("turicas")
77+
print(f"Turicas' channel ID (got from username): {channel_id_2}")
78+
79+
4. Listing Playlists from a Channel:
80+
81+
.. code-block:: python
82+
83+
for playlist in yt.channel_playlists(channel_id_2):
84+
for video in yt.playlist_videos(playlist["id"]):
85+
print(f" Video: {video}")
86+
87+
Here, we iterate through playlists of a specific channel (channel_id_2) and list the videos in each playlist.
88+
89+
5. Searching for Videos:
90+
91+
.. code-block:: python
92+
93+
for index, video in enumerate(yt.video_search(term="Álvaro Justen")):
94+
print(f" Video: {video}")
95+
if index == 4:
96+
break
97+
98+
This snippet searches for videos related to a specific term using the video_search method of the yt instance.
99+
100+
6. Fetching Detailed Video Information:
101+
102+
.. code-block:: python
103+
104+
last_video = list(yt.videos_infos([video["id"]]))[0]
105+
pprint(last_video)
106+
107+
Here, we fetch detailed information about a specific video using the videos_infos method of the yt instance.
108+
109+
7. Fetching Channel Information:
110+
111+
.. code-block:: python
112+
113+
for channel in yt.channels_infos([channel_id_1, channel_id_2]):
114+
print(channel)
115+
116+
This snippet fetches detailed information about multiple channels using the channels_infos method of the yt instance.
117+
118+
8. Fetching Video Comments and Live Chat:
119+
120+
.. code-block:: python
121+
122+
for comment in yt.video_comments(video_id):
123+
print(comment)
124+
for chat_message in yt.video_livechat(live_video_id):
125+
print(chat_message)
126+
127+
Here, we fetch comments and live chat messages from specific videos using the video_comments and video_livechat methods of the yt instance.
128+
129+
9. Downloading Video Transcriptions:
130+
131+
.. code-block:: python
132+
133+
yt.videos_transcriptions([video_id, live_video_id], language_code="pt", path=download_path)
134+
135+
This snippet downloads transcriptions for specific videos using the videos_transcriptions method of the yt instance.
136+
137+
How to contribute
138+
------------------
139+
140+
Welcome to contributing documentation youtool project
141+
142+
See :doc:`contributing` for more detail.
143+
144+
- `Issue Tracker <https://github.com/PythonicCafe/youtool/issues>`_
145+
- `Source Code <https://github.com/PythonicCafe/youtool/blob/develop/youtool.py>`_
146+
147+
Support
148+
-------
149+
150+
If you are having issues, please let us know
151+
152+
License
153+
-------
154+
GNU Lesser General Public License (LGPL) version3
155+
156+
This project was developed in a partnership between Pythonic Café and `Novelo Data <https://www.novelo.io/>`_

‎docs/make.bat‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
@ECHO OFF
2+
3+
pushd %~dp0
4+
5+
REM Command file for Sphinx documentation
6+
7+
if "%SPHINXBUILD%" == "" (
8+
set SPHINXBUILD=sphinx-build
9+
)
10+
set SOURCEDIR=.
11+
set BUILDDIR=_build
12+
13+
%SPHINXBUILD% >NUL 2>NUL
14+
if errorlevel 9009 (
15+
echo.
16+
echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
17+
echo.installed, then set the SPHINXBUILD environment variable to point
18+
echo.to the full path of the 'sphinx-build' executable. Alternatively you
19+
echo.may add the Sphinx directory to PATH.
20+
echo.
21+
echo.If you don't have Sphinx installed, grab it from
22+
echo.https://www.sphinx-doc.org/
23+
exit /b 1
24+
)
25+
26+
if "%1" == "" goto help
27+
28+
%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
29+
goto end
30+
31+
:help
32+
%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
33+
34+
:end
35+
popd

0 commit comments

Comments
 (0)