Skip to content

Commit 685052f

Browse files
jaimeMFjaimeMF
committed
Add initial sphinx docs
With an initial guide for using youtube_dl from python programs.
1 parent f1cef7a commit 685052f

File tree

6 files changed

+341
-0
lines changed

6 files changed

+341
-0
lines changed

‎MANIFEST.in

+2
Original file line numberDiff line numberDiff line change
@@ -3,3 +3,5 @@ include test/*.py
33
include test/*.json
44
include youtube-dl.bash-completion
55
include youtube-dl.1
6+
recursive-include docs *
7+
prune docs/_build

‎docs/.gitignore

+1
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
_build/

‎docs/Makefile

+177
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,177 @@
1+
# Makefile for Sphinx documentation
2+
#
3+
4+
# You can set these variables from the command line.
5+
SPHINXOPTS =
6+
SPHINXBUILD = sphinx-build
7+
PAPER =
8+
BUILDDIR = _build
9+
10+
# User-friendly check for sphinx-build
11+
ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1)
12+
$(error The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx installed, then set the SPHINXBUILD environment variable to point to the full path of the '$(SPHINXBUILD)' executable. Alternatively you can add the directory with the executable to your PATH. If you don't have Sphinx installed, grab it from http://sphinx-doc.org/)
13+
endif
14+
15+
# Internal variables.
16+
PAPEROPT_a4 = -D latex_paper_size=a4
17+
PAPEROPT_letter = -D latex_paper_size=letter
18+
ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
19+
# the i18n builder cannot share the environment and doctrees with the others
20+
I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
21+
22+
.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext
23+
24+
help:
25+
@echo "Please use \`make <target>' where <target> is one of"
26+
@echo " html to make standalone HTML files"
27+
@echo " dirhtml to make HTML files named index.html in directories"
28+
@echo " singlehtml to make a single large HTML file"
29+
@echo " pickle to make pickle files"
30+
@echo " json to make JSON files"
31+
@echo " htmlhelp to make HTML files and a HTML help project"
32+
@echo " qthelp to make HTML files and a qthelp project"
33+
@echo " devhelp to make HTML files and a Devhelp project"
34+
@echo " epub to make an epub"
35+
@echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
36+
@echo " latexpdf to make LaTeX files and run them through pdflatex"
37+
@echo " latexpdfja to make LaTeX files and run them through platex/dvipdfmx"
38+
@echo " text to make text files"
39+
@echo " man to make manual pages"
40+
@echo " texinfo to make Texinfo files"
41+
@echo " info to make Texinfo files and run them through makeinfo"
42+
@echo " gettext to make PO message catalogs"
43+
@echo " changes to make an overview of all changed/added/deprecated items"
44+
@echo " xml to make Docutils-native XML files"
45+
@echo " pseudoxml to make pseudoxml-XML files for display purposes"
46+
@echo " linkcheck to check all external links for integrity"
47+
@echo " doctest to run all doctests embedded in the documentation (if enabled)"
48+
49+
clean:
50+
rm -rf $(BUILDDIR)/*
51+
52+
html:
53+
$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
54+
@echo
55+
@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
56+
57+
dirhtml:
58+
$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
59+
@echo
60+
@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
61+
62+
singlehtml:
63+
$(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml
64+
@echo
65+
@echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."
66+
67+
pickle:
68+
$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
69+
@echo
70+
@echo "Build finished; now you can process the pickle files."
71+
72+
json:
73+
$(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json
74+
@echo
75+
@echo "Build finished; now you can process the JSON files."
76+
77+
htmlhelp:
78+
$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
79+
@echo
80+
@echo "Build finished; now you can run HTML Help Workshop with the" \
81+
".hhp project file in $(BUILDDIR)/htmlhelp."
82+
83+
qthelp:
84+
$(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
85+
@echo
86+
@echo "Build finished; now you can run "qcollectiongenerator" with the" \
87+
".qhcp project file in $(BUILDDIR)/qthelp, like this:"
88+
@echo "# qcollectiongenerator $(BUILDDIR)/qthelp/youtube-dl.qhcp"
89+
@echo "To view the help file:"
90+
@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/youtube-dl.qhc"
91+
92+
devhelp:
93+
$(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp
94+
@echo
95+
@echo "Build finished."
96+
@echo "To view the help file:"
97+
@echo "# mkdir -p $$HOME/.local/share/devhelp/youtube-dl"
98+
@echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/youtube-dl"
99+
@echo "# devhelp"
100+
101+
epub:
102+
$(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub
103+
@echo
104+
@echo "Build finished. The epub file is in $(BUILDDIR)/epub."
105+
106+
latex:
107+
$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
108+
@echo
109+
@echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
110+
@echo "Run \`make' in that directory to run these through (pdf)latex" \
111+
"(use \`make latexpdf' here to do that automatically)."
112+
113+
latexpdf:
114+
$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
115+
@echo "Running LaTeX files through pdflatex..."
116+
$(MAKE) -C $(BUILDDIR)/latex all-pdf
117+
@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
118+
119+
latexpdfja:
120+
$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
121+
@echo "Running LaTeX files through platex and dvipdfmx..."
122+
$(MAKE) -C $(BUILDDIR)/latex all-pdf-ja
123+
@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
124+
125+
text:
126+
$(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text
127+
@echo
128+
@echo "Build finished. The text files are in $(BUILDDIR)/text."
129+
130+
man:
131+
$(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man
132+
@echo
133+
@echo "Build finished. The manual pages are in $(BUILDDIR)/man."
134+
135+
texinfo:
136+
$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
137+
@echo
138+
@echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo."
139+
@echo "Run \`make' in that directory to run these through makeinfo" \
140+
"(use \`make info' here to do that automatically)."
141+
142+
info:
143+
$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
144+
@echo "Running Texinfo files through makeinfo..."
145+
make -C $(BUILDDIR)/texinfo info
146+
@echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo."
147+
148+
gettext:
149+
$(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale
150+
@echo
151+
@echo "Build finished. The message catalogs are in $(BUILDDIR)/locale."
152+
153+
changes:
154+
$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
155+
@echo
156+
@echo "The overview file is in $(BUILDDIR)/changes."
157+
158+
linkcheck:
159+
$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
160+
@echo
161+
@echo "Link check complete; look for any errors in the above output " \
162+
"or in $(BUILDDIR)/linkcheck/output.txt."
163+
164+
doctest:
165+
$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
166+
@echo "Testing of doctests in the sources finished, look at the " \
167+
"results in $(BUILDDIR)/doctest/output.txt."
168+
169+
xml:
170+
$(SPHINXBUILD) -b xml $(ALLSPHINXOPTS) $(BUILDDIR)/xml
171+
@echo
172+
@echo "Build finished. The XML files are in $(BUILDDIR)/xml."
173+
174+
pseudoxml:
175+
$(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) $(BUILDDIR)/pseudoxml
176+
@echo
177+
@echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml."

‎docs/conf.py

+71
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,71 @@
1+
# -*- coding: utf-8 -*-
2+
#
3+
# youtube-dl documentation build configuration file, created by
4+
# sphinx-quickstart on Fri Mar 14 21:05:43 2014.
5+
#
6+
# This file is execfile()d with the current directory set to its
7+
# containing dir.
8+
#
9+
# Note that not all possible configuration values are present in this
10+
# autogenerated file.
11+
#
12+
# All configuration values have a default; values that are commented out
13+
# serve to show the default.
14+
15+
import sys
16+
import os
17+
# Allows to import youtube_dl
18+
sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
19+
20+
# -- General configuration ------------------------------------------------
21+
22+
# Add any Sphinx extension module names here, as strings. They can be
23+
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
24+
# ones.
25+
extensions = [
26+
'sphinx.ext.autodoc',
27+
]
28+
29+
# Add any paths that contain templates here, relative to this directory.
30+
templates_path = ['_templates']
31+
32+
# The suffix of source filenames.
33+
source_suffix = '.rst'
34+
35+
# The master toctree document.
36+
master_doc = 'index'
37+
38+
# General information about the project.
39+
project = u'youtube-dl'
40+
copyright = u'2014, Ricardo Garcia Gonzalez'
41+
42+
# The version info for the project you're documenting, acts as replacement for
43+
# |version| and |release|, also used in various other places throughout the
44+
# built documents.
45+
#
46+
# The short X.Y version.
47+
import youtube_dl
48+
version = youtube_dl.__version__
49+
# The full version, including alpha/beta/rc tags.
50+
release = version
51+
52+
# List of patterns, relative to source directory, that match files and
53+
# directories to ignore when looking for source files.
54+
exclude_patterns = ['_build']
55+
56+
# The name of the Pygments (syntax highlighting) style to use.
57+
pygments_style = 'sphinx'
58+
59+
# -- Options for HTML output ----------------------------------------------
60+
61+
# The theme to use for HTML and HTML Help pages. See the documentation for
62+
# a list of builtin themes.
63+
html_theme = 'default'
64+
65+
# Add any paths that contain custom static files (such as style sheets) here,
66+
# relative to this directory. They are copied after the builtin static files,
67+
# so a file named "default.css" will overwrite the builtin "default.css".
68+
html_static_path = ['_static']
69+
70+
# Output file base name for HTML help builder.
71+
htmlhelp_basename = 'youtube-dldoc'

‎docs/index.rst

+23
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
Welcome to youtube-dl's documentation!
2+
======================================
3+
4+
*youtube-dl* is a command-line program to download videos from YouTube.com and more sites.
5+
It can also be used in Python code.
6+
7+
Developer guide
8+
---------------
9+
10+
This section contains information for using *youtube-dl* from Python programs.
11+
12+
.. toctree::
13+
:maxdepth: 2
14+
15+
module_guide
16+
17+
Indices and tables
18+
==================
19+
20+
* :ref:`genindex`
21+
* :ref:`modindex`
22+
* :ref:`search`
23+

‎docs/module_guide.rst

+67
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,67 @@
1+
Using the ``youtube_dl`` module
2+
===============================
3+
4+
When using the ``youtube_dl`` module, you start by creating an instance of :class:`YoutubeDL` and adding all the available extractors:
5+
6+
.. code-block:: python
7+
8+
>>> from youtube_dl import YoutubeDL
9+
>>> ydl = YoutubeDL()
10+
>>> ydl.add_default_info_extractors()
11+
12+
Extracting video information
13+
----------------------------
14+
15+
You use the :meth:`YoutubeDL.extract_info` method for getting the video information, which returns a dictionary:
16+
17+
.. code-block:: python
18+
19+
>>> info = ydl.extract_info('http://www.youtube.com/watch?v=BaW_jenozKc', download=False)
20+
[youtube] Setting language
21+
[youtube] BaW_jenozKc: Downloading webpage
22+
[youtube] BaW_jenozKc: Downloading video info webpage
23+
[youtube] BaW_jenozKc: Extracting video information
24+
>>> info['title']
25+
'youtube-dl test video "\'/\\ä↭𝕐'
26+
>>> info['height'], info['width']
27+
(720, 1280)
28+
29+
If you want to download or play the video you can get its url:
30+
31+
.. code-block:: python
32+
33+
>>> info['url']
34+
'https://...'
35+
36+
Extracting playlist information
37+
-------------------------------
38+
39+
The playlist information is extracted in a similar way, but the dictionary is a bit different:
40+
41+
.. code-block:: python
42+
43+
>>> playlist = ydl.extract_info('http://www.ted.com/playlists/13/open_source_open_world', download=False)
44+
[TED] open_source_open_world: Downloading playlist webpage
45+
...
46+
>>> playlist['title']
47+
'Open-source, open world'
48+
49+
50+
51+
You can access the videos in the playlist with the ``entries`` field:
52+
53+
.. code-block:: python
54+
55+
>>> for video in playlist['entries']:
56+
... print('Video #%d: %s' % (video['playlist_index'], video['title']))
57+
58+
Video #1: How Arduino is open-sourcing imagination
59+
Video #2: The year open data went worldwide
60+
Video #3: Massive-scale online collaboration
61+
Video #4: The art of asking
62+
Video #5: How cognitive surplus will change the world
63+
Video #6: The birth of Wikipedia
64+
Video #7: Coding a better government
65+
Video #8: The era of open innovation
66+
Video #9: The currency of the new economy is trust
67+

0 commit comments

Comments
 (0)