User Guide: Formatting, link updates

ferdnyc · ferdnyc · commit 5925707a1bea · 2019-12-25T09:16:31.000-05:00
- Add `sphinx.ext.extlinks` extension, and use for repetetive links
- Conditionally enable `sphinx_copybutton` if found
- Wrap inline literals with double \` pairs, to format monospaced
- Turn developer page OS note into a Warning box, and replace the
  outdated PDF install instructions link with links to the Windows
  and Mac build instructions in the libopenshot project wiki
- Wrap paragraphs at periods or commas (sentence-per-line) instead of
  arbitrarily fitting to a certain width
- Use shorter sentences where possible
diff --git a/doc/conf.py b/doc/conf.py
@@ -19,8 +19,9 @@
 #
 import os
 import sys
-sys.path.insert(0, os.path.dirname(os.path.abspath('.')))
-from src.classes import info
+sys.path.insert(0, os.path.join(os.path.dirname(os.path.abspath('.')), "src"))
+
+from classes import info
 
 # -- General configuration ------------------------------------------------
 
@@ -31,7 +32,28 @@
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
-extensions = []
+extensions = [
+    'sphinx.ext.extlinks'
+]
+
+try:
+    # Add Copy button to code cells, if extension is available
+    import sphinx_copybutton
+    extensions.append('sphinx_copybutton')
+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']
@@ -240,21 +262,21 @@
 # -- Options for LaTeX output ---------------------------------------------
 
 latex_elements = {
-     # The paper size ('letterpaper' or 'a4paper').
-     #
-     # 'papersize': 'letterpaper',
+    # The paper size ('letterpaper' or 'a4paper').
+    #
+    # 'papersize': 'letterpaper',
 
-     # The font size ('10pt', '11pt' or '12pt').
-     #
-     # 'pointsize': '10pt',
+    # The font size ('10pt', '11pt' or '12pt').
+    #
+    # 'pointsize': '10pt',
 
-     # Additional stuff for the LaTeX preamble.
-     #
-     # 'preamble': '',
+    # Additional stuff for the LaTeX preamble.
+    #
+    # 'preamble': '',
 
-     # Latex figure (float) alignment
-     #
-     # 'figure_align': 'htbp',
+    # Latex figure (float) alignment
+    #
+    # 'figure_align': 'htbp',
 }
 
 # Grouping the document tree into LaTeX files. List of tuples
diff --git a/doc/contributing.rst b/doc/contributing.rst
@@ -25,12 +25,11 @@ Did you find a bug?
 -------------------
 
 -  **Please check if this bug was already reported** by searching on
-   GitHub under
-   `Issues <https://github.com/OpenShot/openshot-qt/issues>`__.
+   GitHub under `Issues`_.
 
--  If you're unable to find an open issue addressing the problem, `open
-   a new one <https://github.com/OpenShot/openshot-qt/issues/new>`__. Be
-   sure to include a **title and clear description**, as much relevant
+-  If you're unable to find an open issue addressing the problem,
+   :openshot-issue:`open a new one <new/choose>`.
+   Be sure to include a **title and clear description**, as much relevant
    information as possible, and the steps to reproduce the crash or
    issue.
 
@@ -39,7 +38,7 @@ Did you find a bug?
 
 Please download our latest daily installer:
 """""""""""""""""""""""""""""""""""""""""""
-1. `www.openshot.org/download <https://www.openshot.org/download>`__ - click the '**DAILY BUILDS**' button, then grab the latest build from the list.
+1. `openshot.org/download <https://www.openshot.org/download>`_ - click the '**DAILY BUILDS**' button, then grab the latest build from the list.
    (Use the buttons below to download installers for a different Operating System.)
 2. Then enable 'Debug Mode (Verbose)' in the Preferences
 3. Quit OpenShot and delete both log files:
@@ -78,3 +77,5 @@ help us fix them!
 Thanks!
 
 OpenShot Team
+
+.. _Issues: https://github.com/OpenShot/openshot-qt/issues/
diff --git a/doc/developers.rst b/doc/developers.rst
@@ -27,23 +27,34 @@ the following sections will explain how to get started and get involved!
 The Big Picture
 ---------------
 OpenShot Video Editor has 3 main components, a Python & PyQt user interface
-(`openshot-qt <https://github.com/OpenShot/openshot-qt>`_), a C++ audio library
-(`libopenshot-audio <https://github.com/OpenShot/libopenshot-audio>`_) and a C++ video library
-(`libopenshot <https://github.com/OpenShot/libopenshot>`_). If you are not familiar with Python,
+(:openshot-github:`openshot-qt`), a C++ audio library
+(:openshot-github:`libopenshot-audio`) and a C++ video library
+(:openshot-github:`libopenshot`). If you are not familiar with Python,
 PyQt, or C++, those would be great topics to research and learn more about at this point.
 
 However, many bugs and new features can be added with only Python knowledge, since the C++
 components are not involved in the user interface at all. Python is an amazing language, and
 is super fun to learn, and is the only prerequisite skill needed to become an OpenShot
 developer!
 
+.. warning::
+
+    The instructions that follow are for Ubuntu Linux,
+    which is the easiest environment to configure for OpenShot development.
+    If you are using another OS,
+    I suggest running a virtual machine with Ubuntu LTS before continuing any further.
+
+    If you must use a Windows or Mac system for development,
+    start by referring to the build notes in the ``libopenshot`` wiki.
+    Building the library with all of its dependencies is the most challenging part of the process.
+    
+    * :libopenshot-wiki:`Windows Build Instructions <Windows-Build-Instructions>`
+    * :libopenshot-wiki:`Mac Build Instructions <Mac-Build-Instructions>`
+
 Getting the Latest Source Code
 ------------------------------
 Before we can fix any bugs or add any features, we need to get the source code onto your
-computer. These instructions are for Ubuntu Linux, which is the easiest environment to configure
-for OpenShot development. If you are using another OS, I suggest running a virtual machine with
-Ubuntu LTS before continuing any further. If you must use Windows or Mac for development, take a look
-at `these instructions <http://openshot.org/files/libopenshot/InstallationGuide.pdf>`_.
+computer.
 
 Use git to clone our 3 repositories:
 
@@ -96,69 +107,90 @@ great start, and we are now ready to start compiling some code!
 
 libopenshot-audio (Build Instructions)
 --------------------------------------
-This library is required for audio playback and audio effects. It is based on the JUCE audio framework.
-Here are the commands to build and install it:
+This library is required for audio playback and audio effects.
+It is based on the JUCE audio framework.
+Here are the commands to build it:
 
 .. code-block:: bash
 
    cd libopenshot-audio
    mkdir build
    cd build
-   cmake ../
+   cmake -DCMAKE_INSTALL_PREFIX=dist ..
+   make
    make install
 
-Essentially, we are switching to the libopenshot-audio/build folder, and running `cmake ../` on the parent
-folder, which finds dependencies and creates all the needed Makefiles used to compile this library. Then
-`make install` uses those Makefiles to compile, and install this library. This should result in files being
-installed to your /usr/local/ folder.
+Essentially, we are switching to the ``libopenshot-audio/build`` folder,
+then running ``cmake ..`` on the parent folder.
+This finds dependencies and creates all the needed Makefiles used to compile this library.
+Then ``make`` uses those Makefiles to compile this library,
+and ``make install`` installs them in the location we specified.
+If ``CMAKE_INSTALL_PREFIX`` isn't set, the files will install to ``/usr/local/`` (by default) and ``make install`` will require administrative privileges to run.
 
 libopenshot (Build Instructions)
 --------------------------------
-This library is required for video decoding, encoding, animation, and just about everything else. It does all
-the heavy lifting of video editing and video playback. Here are the commands to build and install it.
+This library is required for video decoding, encoding, animation, and just about everything else.
+It does all the heavy lifting of video editing and video playback.
+Here are the commands to build it:
 
 .. code-block:: bash
 
    cd libopenshot
    mkdir build
    cd build
-   cmake ../
-   make install
-
-Essentially, we are switching to the libopenshot/build folder, and running `cmake ../` on the parent
-folder, which finds dependencies and creates all the needed Makefiles used to compile this library. Then
-`make install` uses those Makefiles to compile, and install this library. This should result in files being
-installed to your /usr/local/ folder and in your Python site-packages folder.
-
-openshot-qt (Build Instructions)
---------------------------------
-This is our main PyQt Python application. Because it is written in Python, it does not require any compiling
-to run. To launch openshot-qt from the source code, use the following commands:
+   cmake -DLIBOPENSHOT_AUDIO_DIR=../../libopenshot-audio/build/dist ..
+   make
+
+Essentially, we are switching to the ``libopenshot/build`` folder,
+then running ``cmake ..`` on the parent folder.
+This finds dependencies and creates all the needed Makefiles used to compile this library.
+Then ``make`` uses those Makefiles to compile this library.
+Because we provided the location of our compiled ``libopenshot-audio`` installation,
+that version of the library will be used instead of the system version (if any).
+
+We don't install our ``libopenshot`` after building, because we don't need to.
+For testing purposes, we can tell OpenShot to use ``libopenshot`` right from our ``build`` directory.
+
+openshot-qt (Launch Instructions)
+---------------------------------
+This is our main PyQt Python application.
+Because it is written in Python, it does not require any compiling to run.
+To launch OpenShot from the source code with our newly-built
+``libopenshot-audio`` and ``libopenshot`` libraries, use the following commands:
 
 .. code-block:: bash
 
    cd openshot-qt
+   PYTHONPATH=../libopenshot/build/src/bindings/python
    python3 src/launch.py
 
-This should launch the OpenShot user interface, and include any changes you have made to the source code
-files (`*.py` Python files, `*.ui` PyQt UI files, etc...). This requires the `libopenshot-audio` and
-`libopenshot` libraries, and if anything went wrong with the steps above, OpenShot will likely not launch.
+This should launch the OpenShot user interface.
+Any changes you have made to the source code files
+(``*.py`` Python files, ``*.ui`` PyQt UI files, etc...) will be included.
+This requires the ``libopenshot-audio`` and ``libopenshot`` libraries,
+and if anything went wrong with the steps above, OpenShot will likely not launch.
 
-If OpenShot launches at this point, congratulations, you now have a working local version of OpenShot,
-which is running off your local source code! Try making some changes to the source code and re-launch
-OpenShot... you should now see your changes!
+If OpenShot launches at this point, congratulations!
+You now have a working local version of OpenShot, which is running off your local source code.
+Try making some changes to the source code and re-launch OpenShot...
+you should now see your changes!
 
 GitHub Issues
 -------------
-Now that you have successfully compiled and launched OpenShot Video Editor, be sure to check out our list
-of bug reports on GitHub: https://github.com/OpenShot/openshot-qt/issues. Also, feel free to send me an
-email: jonathan@openshot.org and introduce yourself! I'm always here to help if you have any questions.
+Now that you have successfully compiled and launched OpenShot Video Editor,
+be sure to check out our list of bug reports on GitHub: `OpenShot Issues`_.
+Also, feel free to send me an email:
+`jonathan@openshot.org <mailto:jonathan@openshot.org>`_ and introduce yourself!
+I'm always here to help if you have any questions.
 
 Share your Changes
 ------------------
-Once you have fixed a bug or added an amazing new feature, be sure to share it with the OpenShot team,
-and ideally, we can merge this into our main source code branch. The easiest way to share your changes
-is by creating a fork of our repo, pushing your changes back to GitHub, and creating a
-`Pull Request <https://help.github.com/articles/proposing-changes-to-your-work-with-pull-requests/>`_.
-A Pull Request lets the OpenShot team know you have changes ready to be merged, and we can review things,
-give feedback, and hopefully merge your changes into the main branch.
+Once you have fixed a bug or added an amazing new feature, be sure to share it with the OpenShot team.
+Ideally, we can merge this into our main source code branch.
+The easiest way to share your changes is by creating a fork of our repo,
+pushing your changes back to GitHub, and creating a `Pull Request`_.
+A Pull Request lets the OpenShot team know you have changes ready to be merged.
+Then we can review things, give feedback, and hopefully merge your changes into the main branch.
+
+.. _Pull Request: https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/proposing-changes-to-your-work-with-pull-requests
+.. _OpenShot Issues: https://github.com/OpenShot/openshot-qt/issues/
diff --git a/doc/getting_started.rst b/doc/getting_started.rst
@@ -22,7 +22,7 @@ Getting Started
 
 OpenShot Video Editor is available on most operating systems (including Linux, Mac, and Windows).
 Visit the official download page and grab the latest and greatest version:
-http://www.openshot.org/download/.
+https://www.openshot.org/download/.
 
 Linux
 -----
@@ -42,4 +42,4 @@ Windows
 -------
 Download the Windows installer executable from the project website (listed above), double click it,
 and follow the directions on screen. Once completed, OpenShot will be installed and available
-in your Start menu.
+in your Start menu.
diff --git a/doc/learn_more.rst b/doc/learn_more.rst
@@ -19,5 +19,7 @@
 
 Learn More
 ==========
-We are working hard to expand this user guide, but if you are stuck and don't know where to turn, please
-submit a question or bug report here: https://github.com/OpenShot/openshot-qt/issues
+We are working hard to expand this user guide, but if you are stuck and don't know where to turn,
+please submit a question or bug report here: Issues_.
+
+.. _Issues: https://github.com/OpenShot/openshot-qt/issues/
