From c64b92bf8f732cf61c570c119db564fc155ae7aa Mon Sep 17 00:00:00 2001 From: KongQun Yang Date: Wed, 6 Sep 2017 14:00:18 -0700 Subject: [PATCH] Sphinxdoc configure and other main pages Build sphinx docs in docs/ directory: $ make html The outputs are created in out/sphinx directory. Change-Id: I040915a30aa52d41b18e04741e45622fa61244f6 --- docs/Makefile | 20 ++++ docs/source/conf.py | 180 ++++++++++++++++++++++++++++++++ docs/source/documentation.rst | 80 ++++++++++++++ docs/source/index.rst | 33 ++++++ docs/source/library.rst | 37 +++++++ docs/source/library_details.rst | 44 ++++++++ 6 files changed, 394 insertions(+) create mode 100644 docs/Makefile create mode 100644 docs/source/conf.py create mode 100644 docs/source/documentation.rst create mode 100644 docs/source/index.rst create mode 100644 docs/source/library.rst create mode 100644 docs/source/library_details.rst diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 0000000000..852d95b4c6 --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,20 @@ +# Minimal makefile for Sphinx documentation +# + +# You can set these variables from the command line. +SPHINXOPTS = +SPHINXBUILD = python -msphinx +SPHINXPROJ = ShakaPackager +SOURCEDIR = source +BUILDDIR = ../out/sphinx + +# Put it first so that "make" without argument is like "make help". +help: + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +.PHONY: help Makefile + +# Catch-all target: route all unknown targets to Sphinx using the new +# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). +%: Makefile + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/docs/source/conf.py b/docs/source/conf.py new file mode 100644 index 0000000000..4abdfada9b --- /dev/null +++ b/docs/source/conf.py @@ -0,0 +1,180 @@ +# -*- coding: utf-8 -*- + +"""Shaka Packager documentation build configuration file. + +This file is execfile()d with the current directory set to its +containing dir. + +Note that not all possible configuration values are present in this +autogenerated file. + +All configuration values have a default; values that are commented out +serve to show the default. + +If extensions (or modules to document with autodoc) are in another directory, +add these directories to sys.path here. If the directory is relative to the +documentation root, use os.path.abspath to make it absolute, like shown here. +""" + +from recommonmark.parser import CommonMarkParser + +# sys.path.append('breathe/') + +# -- General configuration ------------------------------------------------ + +# If your documentation needs a minimal Sphinx version, state it here. +# +# needs_sphinx = '1.0' + +# Add any Sphinx extension module names here, as strings. They can be +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom +# ones. +extensions = ['sphinx.ext.autodoc', + 'sphinx.ext.doctest', + 'sphinx.ext.graphviz', + 'sphinx.ext.mathjax', + 'sphinx.ext.viewcode', + 'sphinx.ext.githubpages', + 'cloud_sptheme.ext.table_styling', + 'breathe'] + +# Breathe configurations. +breathe_projects = {'shaka': '../out/doxygen/xml'} +breathe_default_project = 'shaka' +breathe_default_members = ('members',) + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['_templates'] + +source_parsers = { + '.md': CommonMarkParser, +} + +# The suffix(es) of source filenames. +# You can specify multiple suffix as a list of string: +source_suffix = ['.rst', '.md'] + +# The master toctree document. +master_doc = 'index' + +# General information about the project. +project = u'Shaka Packager' +copyright = u'2017, Google' # pylint: disable=redefined-builtin +author = u'Google' + +# The version info for the project you're documenting, acts as replacement for +# |version| and |release|, also used in various other places throughout the +# built documents. +# +# The short X.Y version. +# version = u'2.0' +# The full version, including alpha/beta/rc tags. +# release = u'2.0' + +# The language for content autogenerated by Sphinx. Refer to documentation +# for a list of supported languages. +# +# This is also used if you do content translation via gettext catalogs. +# Usually you set "language" from the command line for these cases. +# language = 'zh_CN' + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +# This patterns also effect to html_static_path and html_extra_path +exclude_patterns = [] + +# The name of the Pygments (syntax highlighting) style to use. +pygments_style = 'sphinx' + +# If true, `todo` and `todoList` produce output, else they produce nothing. +todo_include_todos = False + + +# -- Options for HTML output ---------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +html_theme = 'sphinxdoc' + +# Theme options are theme-specific and customize the look and feel of a theme +# further. For a list of options available for each theme, see the +# documentation. +# +# html_theme_options = {'stickysidebar': 'true'} + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +html_static_path = ['_static'] + +# Custom sidebar templates, must be a dictionary that maps document names +# to template names. +# +# This is required for the alabaster theme +# refs: http://alabaster.readthedocs.io/en/latest/installation.html#sidebars +# html_sidebars = { +# '**': [ +# 'about.html', +# 'navigation.html', +# 'relations.html', # needs 'show_related':True theme option to display +# 'searchbox.html', +# 'donate.html', +# ] +# } + + +# -- Options for HTMLHelp output ------------------------------------------ + +# Output file base name for HTML help builder. +htmlhelp_basename = 'ShakaPackagerdoc' + + +# -- Options for LaTeX output --------------------------------------------- + +latex_elements = { + # The paper size ('letterpaper' or 'a4paper'). + # + # 'papersize': 'letterpaper', + + # The font size ('10pt', '11pt' or '12pt'). + # + # 'pointsize': '10pt', + + # Additional stuff for the LaTeX preamble. + # + # 'preamble': '', + + # Latex figure (float) alignment + # + # 'figure_align': 'htbp', +} + +# Grouping the document tree into LaTeX files. List of tuples +# (source start file, target name, title, +# author, documentclass [howto, manual, or own class]). +latex_documents = [ + (master_doc, 'ShakaPackager.tex', u'Shaka Packager Documentation', + u'Google', 'manual'), +] + + +# -- Options for manual page output --------------------------------------- + +# One entry per manual page. List of tuples +# (source start file, name, description, authors, manual section). +man_pages = [ + (master_doc, 'shakapackager', u'Shaka Packager Documentation', + [author], 1) +] + + +# -- Options for Texinfo output ------------------------------------------- + +# Grouping the document tree into Texinfo files. List of tuples +# (source start file, target name, title, author, +# dir menu entry, description, category) +texinfo_documents = [ + (master_doc, 'ShakaPackager', u'Shaka Packager Documentation', + author, 'ShakaPackager', 'One line description of project.', + 'Miscellaneous'), +] diff --git a/docs/source/documentation.rst b/docs/source/documentation.rst new file mode 100644 index 0000000000..aa7a087fc9 --- /dev/null +++ b/docs/source/documentation.rst @@ -0,0 +1,80 @@ +Packager Documentation +====================== + +Shaka Packager is a tool and a media packaging SDK for DASH and HLS packaging +and encryption. It can transmux input media files from one container to another +container. + +.. note:: + + Shaka Packager does not do transcoding. Content must be pre-encoded before + passing to packager. + +Packager operates in *streams*, described by *stream_descriptor*. The streams +can be read from the same "file" or different "files", which can be regular +files, pipes, udp streams, etc. + +This page is the documentation on using the *packager* tool. If you are +interested in integrating *packager* library into your own tool, please see +:doc:`library`. + +Getting Shaka Packager +---------------------- + +There are several ways you can get Shaka Packager. + +- Using `Docker `_. + Instructions are available at :doc:`docker_instructions`. +- Get prebuilt binaries from + `release `_. +- Built from source, see :doc:`build_instructions` for details. + +Synopsis +-------- + +:: + + $ packager {stream_descriptor} [{stream_descriptor}] ... \ + [--dump_stream_info] \ + [Chunking Options] \ + [MP4 Output Options] \ + [encryption / decryption options] \ + [DASH options] \ + [HLS options] + +.. include:: /options/stream_descriptors.rst + +.. include:: /options/chunking_options.rst + +.. include:: /options/mp4_output_options.rst + +.. include:: /options/dash_options.rst + +.. include:: /options/hls_options.rst + +Encryption / decryption options +------------------------------- + +Shaka Packager supports three different types of key providers: + +- Raw key (fixed key): keys are provided in command line +- Widevine: fetches keys from Widevine key server +- Playready: fetches keys from Playready key server + +Different key providers cannot be specified at the same time. + +:: + + [--enable_widevine_encryption {Widevine Encryption Options}] \ + [--enable_widevine_decryption {Widevine Decryption Options}] \ + [--enable_fixed_key_encryption {Fixed Key Encryption Options}] \ + [--enable_fixed_key_decryption {Fixed Key Decryption Options}] \ + [--enable_playready_encryption {Playready Encryption Options}] + +.. include:: /options/general_encryption_options.rst + +.. include:: /options/raw_key_encryption_options.rst + +.. include:: /options/widevine_encryption_options.rst + +.. include:: /options/playready_encryption_options.rst diff --git a/docs/source/index.rst b/docs/source/index.rst new file mode 100644 index 0000000000..1dd070ed8f --- /dev/null +++ b/docs/source/index.rst @@ -0,0 +1,33 @@ +.. Shaka Packager documentation master file, created by + sphinx-quickstart on Wed Aug 2 12:38:50 2017. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +Welcome to Shaka Packager's documentation! +========================================== + +source code repository: https://github.com/google/shaka-packager + +.. toctree:: + :maxdepth: 2 + + documentation.rst + tutorials/tutorials.rst + library.rst + +.. include a hidden TOC to avoid sphinx complaint. +.. toctree:: + :hidden: + + build_instructions.md + design.rst + docker_instructions.md + library_details.rst + tutorials/encoding.rst + tutorials/ffmpeg_piping.rst + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`search` diff --git a/docs/source/library.rst b/docs/source/library.rst new file mode 100644 index 0000000000..1cffb4abb2 --- /dev/null +++ b/docs/source/library.rst @@ -0,0 +1,37 @@ +Shaka Packager Library +====================== + +Documentation for the top level Shaka packager library. See +`Internal API `_ for +documentation on internal APIs. + +.. doxygenclass:: shaka::Packager + +Sample code: + +.. code-block:: c++ + + shaka::Packager packager; + + // Setup packaging parameters. + shaka::PackagingParams packaging_params; + // Use default parameters here. + + // Setup stream descriptors. + std::vector stream_descriptors; + shaka::StreamDescriptor stream_descriptor; + stream_descriptor.input = "input.mp4"; + stream_descriptor.stream_selector = "video"; + stream_descriptor.output = "output_video.mp4"; + stream_descriptors.push_back(stream_descriptor); + shaka::StreamDescriptor stream_descriptor; + stream_descriptor.input = "input.mp4"; + stream_descriptor.stream_selector = "audio"; + stream_descriptor.output = "output_audio.mp4"; + stream_descriptors.push_back(stream_descriptor); + + shaka::Status status = packager.Initialize(packaging_params, + stream_descriptors); + if (!status.ok()) { ... } + status = packager.Run(); + if (!status.ok()) { ... } diff --git a/docs/source/library_details.rst b/docs/source/library_details.rst new file mode 100644 index 0000000000..06f3d6024f --- /dev/null +++ b/docs/source/library_details.rst @@ -0,0 +1,44 @@ +Shaka Packager Library (Continued) +================================== + +.. doxygenstruct:: shaka::PackagingParams + +.. doxygenstruct:: shaka::StreamDescriptor + +.. doxygenstruct:: shaka::Mp4OutputParams + +.. doxygenstruct:: shaka::ChunkingParams + +.. doxygenstruct:: shaka::MpdParams + +.. doxygenstruct:: shaka::HlsParams + +.. doxygenenum:: shaka::HlsPlaylistType + +.. doxygenenum:: shaka::KeyProvider + +.. doxygenstruct:: shaka::WidevineSigner + +.. doxygenenum:: shaka::WidevineSigner::SigningKeyType + +.. doxygenstruct:: shaka::WidevineEncryptionParams + +.. doxygenstruct:: shaka::PlayreadyEncryptionParams + +.. doxygenstruct:: shaka::RawKeyEncryptionParams + +.. doxygenstruct:: shaka::RawKeyEncryptionParams::KeyPair + +.. doxygenstruct:: shaka::EncryptionParams + +.. doxygenstruct:: shaka::WidevineDecryptionParams + +.. doxygenstruct:: shaka::RawKeyDecryptionParams + +.. doxygenstruct:: shaka::RawKeyDecryptionParams::KeyPair + +.. doxygenstruct:: shaka::DecryptionParams + +.. doxygenclass:: shaka::Status + +.. doxygenenum:: shaka::error::Code