diff --git a/.github/workflows/sphinx.yml b/.github/workflows/sphinx.yml index 5ca970e256..78f90ad6de 100644 --- a/.github/workflows/sphinx.yml +++ b/.github/workflows/sphinx.yml @@ -21,7 +21,8 @@ jobs: steps: # Check out repository under $GITHUB_WORKSPACE - uses: actions/checkout@v2 - # Builds docs using sphinx + + # Build docs using sphinx - uses: ammaraskar/sphinx-action@master with: docs-folder: "doc/" @@ -30,3 +31,13 @@ jobs: with: name: UserGuideHTML path: "doc/_build/html/" + + # Build doc handbook using sphinx + - uses: ammaraskar/sphinx-action@master + with: + docs-folder: "doc/AboutDoc/" + # Create an artifact out of the generated HTML + - uses: actions/upload-artifact@v1 + with: + name: AboutDocHTML + path: "doc/AboutDoc/_build/html/" diff --git a/.gitignore b/.gitignore index a8a5ba423d..8713e89202 100644 --- a/.gitignore +++ b/.gitignore @@ -2,7 +2,6 @@ .idea .settings idea/* -doc/_build **/__pycache__/ build dist diff --git a/doc/.gitignore b/doc/.gitignore new file mode 100644 index 0000000000..68a1b67065 --- /dev/null +++ b/doc/.gitignore @@ -0,0 +1 @@ +**/_build diff --git a/doc/AboutDoc/Documentation_About.rst b/doc/AboutDoc/Documentation_About.rst new file mode 100644 index 0000000000..520789bd9a --- /dev/null +++ b/doc/AboutDoc/Documentation_About.rst @@ -0,0 +1,278 @@ +.. Copyright (c) 2008-2020 OpenShot Studios, LLC + (http://www.openshotstudios.com). This file is part of + OpenShot Video Editor (http://www.openshot.org), an open-source project + dedicated to delivering high quality video editing and animation solutions + to the world. + +.. OpenShot Video Editor is free software: you can redistribute it and/or modify + it under the terms of the GNU General Public License as published by + the Free Software Foundation, either version 3 of the License, or + (at your option) any later version. + +.. OpenShot Video Editor is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + GNU General Public License for more details. + +.. You should have received a copy of the GNU General Public License + along with OpenShot Library. If not, see . + +.. _Documentation_ref: + +About the documentation +======================= + +The source files for the manual are all found in the project repository, `(the doc/ directory) `_ + +The documentation is written in reStructured Text, or ReST. +This is a plain text format encoded in UTF-8. +It contains special syntax so formatting can be applied by third-party tools. +Sphinx is the tool used by OpenShot to create the manual. + +You can suggest improvements or submit small changes for our documentation on our Github here: +https://github.com/OpenShot/openshot-qt/issues/2989 + +.. todo:: + **Discuss if this is needed/desired and if Reddit threads can be pinned to top. ** + Todo: Reddit thread to be made, bookmarked?, add hyperlink + finish line: Or in `this`_ reddit thread. + +The preferred method for submitting large edits would be via GitHub Pull Request. +But we can make accommodations for anyone who would like to contribute but is not familiar with version-control systems like Git. + +License +------- +Project documentation is licensed under the same license as the source code. +Specifically, the GNU General Public License version 3 or higher (GPLv3+); see the document header. +Is is also allows the the documentation to ger prosessed in other tools before it reaches its final form. + +Github +------ +In the issue tracker, subjects that contain explanations that should probably be included in the documentation can be labeled `docs `_\ . +Questions that are answered often in Github can be tagged `FAQ `_ +and can be added to the `Wiki FAQ `_ or better explained in the manual. +Reddit has topic `Addressing Common Issues `_ pinned on the right. + + + | Tutorials for how to add changes to Github: + | Github on Pull requests: https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/creating-a-pull-request-from-a-fork + | Github text howto: https://opensource.com/life/16/3/submit-github-pull-request + | Github video howto: https://www.youtube.com/watch?v=rgbCcBNZcdQ + +It is possible to edit files directly in the Github web interface. +To edit a file via the web interface, +you can just click the pencil icon in its upper-right corner. + +When you started editing, +Github would see that you do not have permissions to make changes directly to files here. +So it would set you up with a copy ("fork") under your account, +where you can make changes before submitting them as a Pull Request. + +Editing on the web is perfectly workable. +Rest files are automatically recognized by Github, to view the plain text version click on **raw** or the **edit** button. +A workflow test is included in the repo, and will be included in the fork. However, you will need to activate this under **Actions** +Once activated, it will automatically run after every commit. +It will also generate the HTML version of the documentation as a so-called *artifact*, +and can be downloaded as ZIP package under the workflow event in the *Action* page. + +With a local clone you can use a previewing editor or +(if you have the necessary Sphinx tools installed) +generate updated HTML docs and view them in a web browser. + +Sphinx +------ +`Spinx `_ was created to simply generate documentation from Python sourcecode. +It is written in Python, and also used in other environments. +It is licensed under the BSD license. +Generating a local copy of the manual requires only the Python-based Sphinx documentation system and the Sphinx RTD theme. +They can be installed using most package managers, or via + +.. code-block:: console + + pip3 install sphinx sphinx-rtd-theme + +Anyone who would like to contribute and needs help with installing and using Sphinx can ask for support in the issues tracker. + +Tutorial video: https://www.youtube.com/watch?v=ouHVkMo3gwE + +ReST Basic Syntax +----------------- +.. TODO:: `List of basic/custom syntax `_ in Openshot documentation. + +- Some explanation here: https://hyperpolyglot.org/lightweight-markup +- or here: https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html +- Sphinx ReST details https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#gotchas +- Video tutorials here: https://www.youtube.com/results?search_query=restructuredtext+tutorial + +Most text editors with syntax highlighting and checking include a ReST language mode or templates can be added. + +A crossplatfom ReST editor with automatic HTML previewing. is ATOM: https://atom.io/ +A Notepad++ ReST template: https://github.com/steenhulthin/reStructuredText_NPP + + +File naming and directory structure +----------------------------------- + +Documentation files are stored in the ``doc/`` directory of the project repository. +Each source file represents one chapter of the User Guide. +The filename is the chapter title, with any spaces replaced by underscores (``_``). +ReStructuredText files have the extension ``.rst``. +Images used in the documentation are in the ``doc/images`` subdirectory. + +.. caution:: + + Documentation filenames must not contain spaces, as they cause problems for Sphinx. + + + +File structure +-------------- + +Every file starts with a hidden 4 paragraph block of the standard header. +It contains the Copyright notice, description of OpenShot, disclaimer and License notice. +(See `template `_ ) +It is sometimes followed by a referral anchor for the title. + +The content starts with a chapter title, double-underlined using equals signs (``=====``). +This is followed by a short introduction describing what will be covered in the chapter. + +A chapter may be divided into sections and subsections, each beginning with an underlined heading. +Like the chapter title, section headings are double-underlined using equals signs. +Subsection headings are single-underlined using hyphens (``----``). + +.. code-block:: ReST + + Chapter title + ============= + + Introduction paragraph. + + Section heading + =============== + + Subsection heading + ------------------ + +Sentences should be written one sentence per line, and do not need to end on a space. +The markup language then flows them all together into paragraphs when it generates the formatted docs. +You can also break at other logical points, like after a comma in a longer sentence, +or before starting an inline markup command. +It is a guideline, not a rule. +This tends to be a pretty good fit for any sort of written prose, when it is in a markup language like ReST and managed in a version control system. + +There are four reasons for this: + +- Writing that way, there is no worrying about line length or when to wrap. +- The diffs when changes are submitted also tend to be more readable and focused. +- It encourages shorter, simpler sentences which is a good thing when writing docs. +- Short lines are easier to translate as they are less likely to be changed. + +Comments for why things are documented a certain way can be hidden after a double dot and start with "NOTE: ". +They may contain a link to a relevant issue in the tracker for more information. + +But comments regarding issues that are not complete (like new features) should be marked with the tag \.. TODO:: +They will be emphasized by Github but filtered out of the final user documentation by Sphinx. + + + +.. todo:: + ** After finding out how translation files can be created, update this paragraph.** + + Translation + ----------- + + Translation files are generated and managed by Sphinx. + If the images are not translated, they will default back to the original. + Filenames do not get translated. + There may be translation notes hidden in the documentation, blocked out with \.. TRANSLATION NOTE: + Files for translation will be hosted at `Launchpad `_. + When translating numbers referencing a screenshot in non-western languages, please make sure to update the screenshot too. + If available, images of the translation should be saved in their subdirectory *(to be decided)* + + .. TODO:: Add subdirectory + + .. TRANSLATION NOTE: After translating tables make sure they do not break. The underlining of table rows needs to be the same length as the new words. + + +Images +------ + +.. caution:: Please make sure to add your images under the GPL3 as well. + +**PNG** is the preferred format for screenshots, as it's not subject to compression artifacts the way JPG is. +JPG is fine too, if the quality is high enough (Compression of 90% or better). +Clarity is the priority, not file size. + +Animated GIFs are not suitable as screenshots, because the animated component is only visible when the docs are viewed in web form. +Also the quality and/or file size ratio tends to be abysmal and thus multi-megabyte GIFs can take forever to download and start animating. +They are however suitable as alternative to Video. + +Images should be **696px wide** at their **maximum**. +The page layout has a width cap that makes it the effective maximum width for images. +For this reason 4:3 pictures are preferred over widescreen. +Images should be whatever shape they need to be in order to show the necessary information, there is no fixed aspect. +But since images will be scaled to fit the width of the page, in general images should not be unnecessarily wide. +Otherwise they can end up too small when displayed. + +.. TODO:: Image width Verification Needed: + Is this set in the server? Does it apply to all browsers? Does this apply to offline docs too? + From a test by ferdnyc "when I have a Chrome window open with the manual loaded into it, once the window hits about 1160px wide, that's it — the content stops getting any wider. Past that width (which is including the sidebar), the only thing that grows is the empty space to the right of the content container. And at that size, the images are scaled to 696px wide." + https://github.com/OpenShot/openshot-qt/issues/2989 + +There is no demo art package available for screenshots. +Screenshots showing different content is an opportunity to illustrate the variety of different features and configurations available. +However during a step-by-step tutorial for a feature, it makes sense to have a set of consistent imports for all of the steps. +So that the illustrations reflect exactly what the user would expect to see in the actual software. + +Images should be named descriptively, so the names have relevance long-term. +It should say what it is, and it should be what it says. +I suitable, they can be named for the tutorial page they belong to. + +They can be named for Action-WindowName or ActionStepNumber. +Images belonging to a sequence should be numbered. +Names like intro-tutorial-step-1.png (followed by -step-2.png through -step-n.png), +interface-export-simple.png and so on. + +.. TODO:: QUESTION: Should image sequences be in the same resolution? So they can be combined to animation? + +Tutorial art +------------ +The color for arrows is *#aec255ff* + +The green contrasts well with the dark GUI of Openshot +The font used in the art is *Ubuntu* and can be found in the repo or the Openshot installation. + +There is a green call-out circle used for numbering in the repo under docs/images/circle.svg. +It is editable in software that can edit SVG files (e.g. Inkscape and Illustrator). +The green arrow is not yet in the repo. + +.. TODO:: PROPOSAL: save all tutorial art into docs/pointers/ or something like that? +.. TODO:: Upload font and callout circle to dir +.. TODO:: Question: because it is an SVG, is the number changed in ReST? + +Video +----- +The manual should ideally be useful in print form as well, +but for extra clarification a video or GIF can be included. +Any animated elements should enhance the information presented in the static content, rather than replace it. +Whatever happens in the animation should also be described in full detail in the accompanying text. +So make sure a description and pictures are suitable for offline documentation first. + +Video may be preferable over animated GIF, because embedded videos are clearer and higher quality. +They are also click-to-play which avoids forcing a large initial download on the user. +For short actions, GIFS may however be a lot easier. + +Beside GIF, only Youtube videos can be embedded with the tag +\.. youtube \:: + +.. NOTE: https://github.com/OpenShot/openshot-qt/pull/3394 + +Tables +------ + +.. TODO:: Table specifications + +| Todo: Issues with tables +| https://github.com/OpenShot/openshot-qt/issues/1262 +| https://github.com/OpenShot/openshot-qt/pull/1272 + diff --git a/doc/AboutDoc/Makefile b/doc/AboutDoc/Makefile new file mode 100644 index 0000000000..0828e7a173 --- /dev/null +++ b/doc/AboutDoc/Makefile @@ -0,0 +1,225 @@ +# Makefile for Sphinx documentation +# + +# You can set these variables from the command line. +SPHINXOPTS = +SPHINXBUILD = sphinx-build +PAPER = +BUILDDIR = _build + +# Internal variables. +PAPEROPT_a4 = -D latex_paper_size=a4 +PAPEROPT_letter = -D latex_paper_size=letter +ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . +# the i18n builder cannot share the environment and doctrees with the others +I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . + +.PHONY: help +help: + @echo "Please use \`make ' where is one of" + @echo " html to make standalone HTML files" + @echo " dirhtml to make HTML files named index.html in directories" + @echo " singlehtml to make a single large HTML file" + @echo " pickle to make pickle files" + @echo " json to make JSON files" + @echo " htmlhelp to make HTML files and a HTML help project" + @echo " qthelp to make HTML files and a qthelp project" + @echo " applehelp to make an Apple Help Book" + @echo " devhelp to make HTML files and a Devhelp project" + @echo " epub to make an epub" + @echo " epub3 to make an epub3" + @echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter" + @echo " latexpdf to make LaTeX files and run them through pdflatex" + @echo " latexpdfja to make LaTeX files and run them through platex/dvipdfmx" + @echo " text to make text files" + @echo " man to make manual pages" + @echo " texinfo to make Texinfo files" + @echo " info to make Texinfo files and run them through makeinfo" + @echo " gettext to make PO message catalogs" + @echo " changes to make an overview of all changed/added/deprecated items" + @echo " xml to make Docutils-native XML files" + @echo " pseudoxml to make pseudoxml-XML files for display purposes" + @echo " linkcheck to check all external links for integrity" + @echo " doctest to run all doctests embedded in the documentation (if enabled)" + @echo " coverage to run coverage check of the documentation (if enabled)" + @echo " dummy to check syntax errors of document sources" + +.PHONY: clean +clean: + rm -rf $(BUILDDIR)/* + +.PHONY: html +html: + $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html + @echo + @echo "Build finished. The HTML pages are in $(BUILDDIR)/html." + +.PHONY: dirhtml +dirhtml: + $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml + @echo + @echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml." + +.PHONY: singlehtml +singlehtml: + $(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml + @echo + @echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml." + +.PHONY: pickle +pickle: + $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle + @echo + @echo "Build finished; now you can process the pickle files." + +.PHONY: json +json: + $(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json + @echo + @echo "Build finished; now you can process the JSON files." + +.PHONY: htmlhelp +htmlhelp: + $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp + @echo + @echo "Build finished; now you can run HTML Help Workshop with the" \ + ".hhp project file in $(BUILDDIR)/htmlhelp." + +.PHONY: qthelp +qthelp: + $(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp + @echo + @echo "Build finished; now you can run "qcollectiongenerator" with the" \ + ".qhcp project file in $(BUILDDIR)/qthelp, like this:" + @echo "# qcollectiongenerator $(BUILDDIR)/qthelp/OpenShotVideoEditor.qhcp" + @echo "To view the help file:" + @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/OpenShotVideoEditor.qhc" + +.PHONY: applehelp +applehelp: + $(SPHINXBUILD) -b applehelp $(ALLSPHINXOPTS) $(BUILDDIR)/applehelp + @echo + @echo "Build finished. The help book is in $(BUILDDIR)/applehelp." + @echo "N.B. You won't be able to view it unless you put it in" \ + "~/Library/Documentation/Help or install it in your application" \ + "bundle." + +.PHONY: devhelp +devhelp: + $(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp + @echo + @echo "Build finished." + @echo "To view the help file:" + @echo "# mkdir -p $$HOME/.local/share/devhelp/OpenShotVideoEditor" + @echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/OpenShotVideoEditor" + @echo "# devhelp" + +.PHONY: epub +epub: + $(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub + @echo + @echo "Build finished. The epub file is in $(BUILDDIR)/epub." + +.PHONY: epub3 +epub3: + $(SPHINXBUILD) -b epub3 $(ALLSPHINXOPTS) $(BUILDDIR)/epub3 + @echo + @echo "Build finished. The epub3 file is in $(BUILDDIR)/epub3." + +.PHONY: latex +latex: + $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex + @echo + @echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex." + @echo "Run \`make' in that directory to run these through (pdf)latex" \ + "(use \`make latexpdf' here to do that automatically)." + +.PHONY: latexpdf +latexpdf: + $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex + @echo "Running LaTeX files through pdflatex..." + $(MAKE) -C $(BUILDDIR)/latex all-pdf + @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." + +.PHONY: latexpdfja +latexpdfja: + $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex + @echo "Running LaTeX files through platex and dvipdfmx..." + $(MAKE) -C $(BUILDDIR)/latex all-pdf-ja + @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." + +.PHONY: text +text: + $(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text + @echo + @echo "Build finished. The text files are in $(BUILDDIR)/text." + +.PHONY: man +man: + $(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man + @echo + @echo "Build finished. The manual pages are in $(BUILDDIR)/man." + +.PHONY: texinfo +texinfo: + $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo + @echo + @echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo." + @echo "Run \`make' in that directory to run these through makeinfo" \ + "(use \`make info' here to do that automatically)." + +.PHONY: info +info: + $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo + @echo "Running Texinfo files through makeinfo..." + make -C $(BUILDDIR)/texinfo info + @echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo." + +.PHONY: gettext +gettext: + $(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale + @echo + @echo "Build finished. The message catalogs are in $(BUILDDIR)/locale." + +.PHONY: changes +changes: + $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes + @echo + @echo "The overview file is in $(BUILDDIR)/changes." + +.PHONY: linkcheck +linkcheck: + $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck + @echo + @echo "Link check complete; look for any errors in the above output " \ + "or in $(BUILDDIR)/linkcheck/output.txt." + +.PHONY: doctest +doctest: + $(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest + @echo "Testing of doctests in the sources finished, look at the " \ + "results in $(BUILDDIR)/doctest/output.txt." + +.PHONY: coverage +coverage: + $(SPHINXBUILD) -b coverage $(ALLSPHINXOPTS) $(BUILDDIR)/coverage + @echo "Testing of coverage in the sources finished, look at the " \ + "results in $(BUILDDIR)/coverage/python.txt." + +.PHONY: xml +xml: + $(SPHINXBUILD) -b xml $(ALLSPHINXOPTS) $(BUILDDIR)/xml + @echo + @echo "Build finished. The XML files are in $(BUILDDIR)/xml." + +.PHONY: pseudoxml +pseudoxml: + $(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) $(BUILDDIR)/pseudoxml + @echo + @echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml." + +.PHONY: dummy +dummy: + $(SPHINXBUILD) -b dummy $(ALLSPHINXOPTS) $(BUILDDIR)/dummy + @echo + @echo "Build finished. Dummy builder generates no files." diff --git a/doc/AboutDoc/conf.py b/doc/AboutDoc/conf.py new file mode 100644 index 0000000000..5f5397c013 --- /dev/null +++ b/doc/AboutDoc/conf.py @@ -0,0 +1,454 @@ +#!/usr/bin/env python3 +# -*- coding: utf-8 -*- +# +# OpenShot Video Editor documentation build configuration file, created by +# sphinx-quickstart on Thu Sep 22 22:32:39 2016. +# +# 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. +# +import os +import sys + +# -- 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.extlinks', + 'sphinx.ext.todo', +] + +try: + # Add Copy button to code cells, if extension is available + import sphinx_copybutton + extensions.append('sphinx_copybutton') +except ImportError: + pass + +import sys +sys.path.insert(0, '.') +try: + # Load our YouTube directive + import youtube_directive + extensions.append('youtube_directive') +except ImportError: + pass + +# External links mappings for extlinks +# see: http://www.sphinx-doc.org/en/master/usage/extensions/extlinks.html +extlinks = { + # alias: (url_template, prefix) + 'openshot-github': + ('https://github.com/OpenShot/%s', ''), + 'libopenshot-wiki': + ('https://github.com/OpenShot/libopenshot/wiki/%s', ''), + 'openshot-issue': + ('https://github.com/OpenShot/openshot-qt/issues/%s', 'issue ') +} + +# Add any paths that contain templates here, relative to this directory. +#templates_path = ['_templates'] + +# The suffix(es) of source filenames. +# You can specify multiple suffix as a list of string: +# +# source_suffix = ['.rst', '.md'] +source_suffix = '.rst' + +# The encoding of source files. +# +# source_encoding = 'utf-8-sig' + +# The master toctree document. +master_doc = 'index' + +# General information about the project. +project = 'OpenShot Documentation Writers Handbook' +#copyright = +#author = + +# 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 = "0.1" +# The full version, including alpha/beta/rc tags. +release = version + +# 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 = None + +# There are two options for replacing |today|: either, you set today to some +# non-false value, then it is used: +# +# today = '' +# +# Else, today_fmt is used as the format for a strftime call. +# +# today_fmt = '%B %d, %Y' + +# 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 = ['_build', 'Thumbs.db', '.DS_Store'] + +# The reST default role (used for this markup: `text`) to use for all +# documents. +# +# default_role = None + +# If true, '()' will be appended to :func: etc. cross-reference text. +# +# add_function_parentheses = True + +# If true, the current module name will be prepended to all description +# unit titles (such as .. function::). +# +# add_module_names = True + +# If true, sectionauthor and moduleauthor directives will be shown in the +# output. They are ignored by default. +# +# show_authors = False + +# The name of the Pygments (syntax highlighting) style to use. +pygments_style = 'sphinx' + +# A list of ignored prefixes for module index sorting. +# modindex_common_prefix = [] + +# If true, keep warnings as "system message" paragraphs in the built documents. +# keep_warnings = False + +# If true, `todo` and `todoList` produce output, else they produce nothing. +todo_include_todos = True + + +# -- 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 = 'sphinx_rtd_theme' + +# 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 = {} + +# Add any paths that contain custom themes here, relative to this directory. +#html_theme_path = ["_themes", ] + +# The name for this set of Sphinx documents. +# " v documentation" by default. +# +# html_title = 'OpenShot Video Editor v2.1.0' + +# A shorter title for the navigation bar. Default is the same as html_title. +# +# html_short_title = None + +# The name of an image file (relative to this directory) to place at the top +# of the sidebar. +# +html_logo = "../../xdg/openshot-arrow.png" + +# The name of an image file (relative to this directory) to use as a favicon of +# the docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 +# pixels large. +# +html_favicon = "../../xdg/openshot-qt.ico" + +# 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 = ['../css'] + +# Add any extra paths that contain custom files (such as robots.txt or +# .htaccess) here, relative to this directory. These files are copied +# directly to the root of the documentation. +# +# html_extra_path = [] + +# If not None, a 'Last updated on:' timestamp is inserted at every page +# bottom, using the given strftime format. +# The empty string is equivalent to '%b %d, %Y'. +# +# html_last_updated_fmt = None + +# If true, SmartyPants will be used to convert quotes and dashes to +# typographically correct entities. +# +# html_use_smartypants = True + +# Custom sidebar templates, maps document names to template names. +# +# html_sidebars = {} + +# Additional templates that should be rendered to pages, maps page names to +# template names. +# +# html_additional_pages = {} + +# If false, no module index is generated. +# +# html_domain_indices = True + +# If false, no index is generated. +# +# html_use_index = True + +# If true, the index is split into individual pages for each letter. +# +# html_split_index = False + +# If true, links to the reST sources are added to the pages. +# +# html_show_sourcelink = True + +# If true, "Created using Sphinx" is shown in the HTML footer. Default is True. +# +#html_show_sphinx = False + +# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True. +# +# html_show_copyright = True + +# If true, an OpenSearch description file will be output, and all pages will +# contain a tag referring to it. The value of this option must be the +# base URL from which the finished HTML is served. +# +# html_use_opensearch = '' + +# This is the file name suffix for HTML files (e.g. ".xhtml"). +# html_file_suffix = None + +# Language to be used for generating the HTML full-text search index. +# Sphinx supports the following languages: +# 'da', 'de', 'en', 'es', 'fi', 'fr', 'h', 'it', 'ja' +# 'nl', 'no', 'pt', 'ro', 'r', 'sv', 'tr', 'zh' +# +# html_search_language = 'en' + +# A dictionary with options for the search language support, empty by default. +# 'ja' uses this config value. +# 'zh' user can custom change `jieba` dictionary path. +# +# html_search_options = {'type': 'default'} + +# The name of a javascript file (relative to the configuration directory) that +# implements a search results scorer. If empty, the default will be used. +# +# html_search_scorer = 'scorer.js' + +# Output file base name for HTML help builder. +#htmlhelp_basename = 'OpenShotVideoEditordoc' + +# -- 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, 'OpenShotVideoEditor.tex', 'OpenShot Video Editor Documentation', +# 'Jonathan Thomas', 'manual'), +#] + +# The name of an image file (relative to this directory) to place at the top of +# the title page. +# +# latex_logo = None + +# For "manual" documents, if this is true, then toplevel headings are parts, +# not chapters. +# +# latex_use_parts = False + +# If true, show page references after internal links. +# +# latex_show_pagerefs = False + +# If true, show URL addresses after external links. +# +# latex_show_urls = False + +# Documents to append as an appendix to all manuals. +# +# latex_appendices = [] + +# It false, will not define \strong, \code, itleref, \crossref ... but only +# \sphinxstrong, ..., \sphinxtitleref, ... To help avoid clash with user added +# packages. +# +# latex_keep_old_macro_names = True + +# If false, no module index is generated. +# +# latex_domain_indices = True + + +# -- 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, 'openshotvideoeditor', 'OpenShot Video Editor Documentation', +# [author], 1) +#] + +# If true, show URL addresses after external links. +# +# man_show_urls = False + + +# -- 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, 'OpenShotVideoEditor', 'OpenShot Video Editor Documentation', +# author, 'OpenShotVideoEditor', 'One line description of project.', +# 'Miscellaneous'), +#] + +# Documents to append as an appendix to all manuals. +# +# texinfo_appendices = [] + +# If false, no module index is generated. +# +# texinfo_domain_indices = True + +# How to display URL addresses: 'footnote', 'no', or 'inline'. +# +# texinfo_show_urls = 'footnote' + +# If true, do not generate a @detailmenu in the "Top" node's menu. +# +# texinfo_no_detailmenu = False + + +# -- Options for Epub output ---------------------------------------------- + +# Bibliographic Dublin Core info. +#epub_title = project +#epub_author = author +#epub_publisher = author +#epub_copyright = copyright + +# The basename for the epub file. It defaults to the project name. +# epub_basename = project + +# The HTML theme for the epub output. Since the default themes are not +# optimized for small screen space, using the same theme for HTML and epub +# output is usually not wise. This defaults to 'epub', a theme designed to save +# visual space. +# +# epub_theme = 'epub' + +# The language of the text. It defaults to the language option +# or 'en' if the language is not set. +# +# epub_language = '' + +# The scheme of the identifier. Typical schemes are ISBN or URL. +# epub_scheme = '' + +# The unique identifier of the text. This can be a ISBN number +# or the project homepage. +# +# epub_identifier = '' + +# A unique identification for the text. +# +# epub_uid = '' + +# A tuple containing the cover image and cover page html template filenames. +# +# epub_cover = () + +# A sequence of (type, uri, title) tuples for the guide element of content.opf. +# +# epub_guide = () + +# HTML files that should be inserted before the pages created by sphinx. +# The format is a list of tuples containing the path and title. +# +# epub_pre_files = [] + +# HTML files that should be inserted after the pages created by sphinx. +# The format is a list of tuples containing the path and title. +# +# epub_post_files = [] + +# A list of files that should not be packed into the epub file. +#epub_exclude_files = ['search.html'] + +# The depth of the table of contents in toc.ncx. +# +# epub_tocdepth = 3 + +# Allow duplicate toc entries. +# +# epub_tocdup = True + +# Choose between 'default' and 'includehidden'. +# +# epub_tocscope = 'default' + +# Fix unsupported image types using the Pillow. +# +# epub_fix_images = False + +# Scale large images. +# +# epub_max_image_width = 0 + +# How to display URL addresses: 'footnote', 'no', or 'inline'. +# +# epub_show_urls = 'inline' + +# If false, no index is generated. +# +# epub_use_index = True diff --git a/doc/AboutDoc/index.rst b/doc/AboutDoc/index.rst new file mode 100644 index 0000000000..f4ed0ff1f9 --- /dev/null +++ b/doc/AboutDoc/index.rst @@ -0,0 +1,38 @@ +.. Copyright (c) 2008-2016 OpenShot Studios, LLC + (http://www.openshotstudios.com). This file is part of + OpenShot Video Editor (http://www.openshot.org), an open-source project + dedicated to delivering high quality video editing and animation solutions + to the world. + +.. OpenShot Video Editor is free software: you can redistribute it and/or modify + it under the terms of the GNU General Public License as published by + the Free Software Foundation, either version 3 of the License, or + (at your option) any later version. + +.. OpenShot Video Editor is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + GNU General Public License for more details. + +.. You should have received a copy of the GNU General Public License + along with OpenShot Library. If not, see . + +.. |title| replace:: OpenShot Documentation Writers Handbook + +|title| +=================== + +OpenShot Video Editor is an award-winning, open-source video editor, available on Linux, Mac, and Windows. +OpenShot can create stunning videos, films, and animations with an easy-to-use interface and rich set of features. + +Writing OpenShot documentation is easy and fun! +With this guide, you will be a master in no time at all. + +Table of Contents: +------------------ + +.. toctree:: + :maxdepth: 2 + + Documentation_About + template diff --git a/doc/AboutDoc/requirements.txt b/doc/AboutDoc/requirements.txt new file mode 100644 index 0000000000..eddacb0dba --- /dev/null +++ b/doc/AboutDoc/requirements.txt @@ -0,0 +1,3 @@ +sphinx_rtd_theme +sphinx_copybutton + diff --git a/doc/AboutDoc/template.rst b/doc/AboutDoc/template.rst new file mode 100644 index 0000000000..40b1f55dce --- /dev/null +++ b/doc/AboutDoc/template.rst @@ -0,0 +1,28 @@ +.. Copyright (c) 2008-2020 OpenShot Studios, LLC + (http://www.openshotstudios.com). This file is part of + OpenShot Video Editor (http://www.openshot.org), an open-source project + dedicated to delivering high quality video editing and animation solutions + to the world. + +.. OpenShot Video Editor is free software: you can redistribute it and/or modify + it under the terms of the GNU General Public License as published by + the Free Software Foundation, either version 3 of the License, or + (at your option) any later version. + +.. OpenShot Video Editor is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + GNU General Public License for more details. + +.. You should have received a copy of the GNU General Public License + along with OpenShot Library. If not, see . + +.. _TitleAnchor_ref: + +Title +===== + +Summary + +Subtitle +-------- diff --git a/doc/_templates/layout.html b/doc/_templates/layout.html index d47dc3284d..52381c8cb6 100644 --- a/doc/_templates/layout.html +++ b/doc/_templates/layout.html @@ -1,2 +1,3 @@ {% extends "!layout.html" %} -{% set css_files = css_files + ["_static/tablefix.css"] %} +{% set css_files = css_files + ["_static/openshot.css"] %} + diff --git a/doc/conf.py b/doc/conf.py index 155e64279c..3695d5aafc 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -33,7 +33,8 @@ # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom # ones. extensions = [ - 'sphinx.ext.extlinks' + 'sphinx.ext.extlinks', + 'sphinx.ext.todo', ] try: @@ -113,7 +114,7 @@ # 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 = ['_build', 'Thumbs.db', '.DS_Store'] +exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store', 'AboutDoc'] # The reST default role (used for this markup: `text`) to use for all # documents. diff --git a/doc/css/openshot.css b/doc/css/openshot.css new file mode 100644 index 0000000000..c9bcfeba60 --- /dev/null +++ b/doc/css/openshot.css @@ -0,0 +1,82 @@ +/* override table width restrictions */ +.wy-table-responsive table td, .wy-table-responsive table th { + white-space: normal; +} +div.wy-table-responsive { + margin-bottom: 24px; + max-width: 100%; + overflow: visible; +} + +/* Fix crazy-tall table headers */ +.wy-table-responsive th p { + margin-bottom: unset; +} + +/* Raise max content width */ +.wy-nav-content { + max-width: 1000px; +} + +/* Format menuselection so it stands out */ +.menuselection { + font-weight: bold; + white-space: nowrap; + font-size: 90%; + font-family: "Segoe UI", Verdana, "Droid Sans", sans-serif; +} +/* Allow wrapping on small screens */ +@media screen and (max-width: 450px) { + .menuselection { white-space: normal; } +} + +/* Format guilabel so it stands out LESS */ +.rst-content .guilabel { + font-size: 90%; + font-weight: 500; + font-family: "Segoe UI", Verdana, "Droid Sans", Arial, sans-serif; + border: 1px solid #c2c2c2; + background: #f2f2f2; +} + +/* Don't color file paths red or render so small */ +.rst-content code.file, .rst-content code.literal { + color: black; + font-size: 90%; +} + +/* + * More color-coding for admonition box types + */ + +/* Red CAUTION boxes */ +.rst-content .caution { + background: #ffdfcc; +} +.rst-content .caution .admonition-title { + background: #f0837e; +} + +/* Space out inline images just a bit */ +p img, td img { + margin-left: 3px; + margin-right: 3px; +} + +/* Keyboard styling (borrowed from GitHub) */ +kbd { + display: inline-block; + padding: 2.6px 5px; + font-size: 13px; + line-height: 1.15; + color: #444d56; + vertical-align: middle; + background-color: #fafbfc; + border: solid 1px #c6cbd1; + border-bottom-color: #959da5; + border-radius: 3px; + box-shadow: inset 0 -1px 0 #959da5 +} + +/* Underlining for accelerators in menuselection and guilabel */ +.accelerator { text-decoration: underline; } diff --git a/doc/css/tablefix.css b/doc/css/tablefix.css deleted file mode 100644 index 3151dc1ea3..0000000000 --- a/doc/css/tablefix.css +++ /dev/null @@ -1,14 +0,0 @@ -/* override table width restrictions */ -.wy-table-responsive table td, .wy-table-responsive table th { - white-space: normal; -} - -.wy-table-responsive { - margin-bottom: 24px; - max-width: 100%; - overflow: visible; -} - -.wy-table-responsive th p { - margin-bottom: unset; -}