Merge pull request #1333 from chrissimpkins/readthedocs

.readthedocs.yml

@@ -0,0 +1,27 @@
+# .readthedocs.yml
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+build:
+  image: latest
+
+# Build documentation in the docs/ directory with Sphinx
+sphinx:
+  configuration: Doc/source/conf.py
+  fail_on_warning: false
+
+# Optionally build your docs in additional formats such as PDF and ePub
+formats: all
+
+# Optionally set the version of Python and requirements required to build your docs
+python:
+  version: 3.8
+  install:
+    - requirements: Doc/docs-requirements.txt
+    - method: pip
+    path: .
+    extra_requirements:
+      - all

Doc/README.md

@@ -0,0 +1,121 @@
+# fontTools Documentation
+
+The fontTools project documentation updates continuously on Read the Docs as the project source changes.  
+
+The documentation is hosted at https://fonttools.readthedocs.io/.
+
+## Contents
+
+- [How to Build Local Documentation](#how-to-build-local-documentation)
+- [Contributing to the fontTools Documentation](#contributing-to-the-documentation)
+- [Documentation License](#documentation-license)
+
+## How to Build Local Documentation
+
+### Install Dependencies
+
+You must have a Python 3 interpreter and the `pip` Python package manager installed on your system to build the fontTools documentation.
+
+Pull the fontTools project source files, create a Python virtual environment, and then install fontTools and the documentation build dependencies by executing the following commands in the root of the fontTools source repository:
+
+```
+$ pip install -e . [all]
+$ pip install -r Doc/docs-requirements.txt
+```
+
+### Build Documentation
+
+**With `make`**: execute the following command in the root of the repository:
+
+```
+$ make docs
+```
+
+**Without `make`**: execute the following command in the **`Doc` directory**:
+
+```
+$ sphinx-build -b html source build
+```
+
+Open the `Doc/build/html/index.html` file in your browser to view the documentation home page.
+
+## Contributing to the Documentation
+
+We highly encourage contributions!  Please follow the instructions below to improve the documentation.
+
+### Python Docstring Style
+
+We recommend the use of Python docstrings that follow [the Google Style Guide](https://github.com/google/styleguide/blob/gh-pages/pyguide.md#381-docstrings).  Our documentation build approach parses appropriately formatted docstrings into formatted documentation files.
+
+#### Function Documentation Example
+
+```python
+def fetch_bigtable_rows(big_table, keys, other_silly_variable=None):
+    """Fetches rows from a Bigtable.
+
+    Retrieves rows pertaining to the given keys from the Table instance
+    represented by big_table.  Silly things may happen if
+    other_silly_variable is not None.
+
+    Args:
+        big_table: An open Bigtable Table instance.
+        keys: A sequence of strings representing the key of each table row
+            to fetch.
+        other_silly_variable: Another optional variable, that has a much
+            longer name than the other args, and which does nothing.
+
+    Returns:
+        A dict mapping keys to the corresponding table row data
+        fetched. Each row is represented as a tuple of strings. For
+        example:
+
+        {'Serak': ('Rigel VII', 'Preparer'),
+         'Zim': ('Irk', 'Invader'),
+         'Lrrr': ('Omicron Persei 8', 'Emperor')}
+
+        If a key from the keys argument is missing from the dictionary,
+        then that row was not found in the table.
+
+    Raises:
+        IOError: An error occurred accessing the bigtable.Table object.
+    """
+```
+*Source: [Google Style Guide](https://github.com/google/styleguide/blob/gh-pages/pyguide.md) (CC BY-SA 3.0)*
+
+#### Class Documentation Example
+
+```python
+class SampleClass(object):
+    """Summary of class here.
+
+    Longer class information....
+    Longer class information....
+
+    Attributes:
+        likes_spam: A boolean indicating if we like SPAM or not.
+        eggs: An integer count of the eggs we have laid.
+    """
+
+    def __init__(self, likes_spam=False):
+        """Inits SampleClass with blah."""
+        self.likes_spam = likes_spam
+        self.eggs = 0
+
+    def public_method(self):
+        """Performs operation blah."""
+```
+*Source: [Google Style Guide](https://github.com/google/styleguide/blob/gh-pages/pyguide.md) (CC BY-SA 3.0)*
+
+### Build Local Documentation and Review Your Changes
+
+Build a local set of HTML documentation files with the instructions above and review your changes.
+
+### Submit a Pull Request
+
+Submit a Github pull request with your proposed improvements to the documentation.  
+
+Thanks for your contribution!
+
+## Documentation License
+
+The fontTools documentation is released under a [CC BY-SA 4.0 International License](https://creativecommons.org/licenses/by-sa/4.0/).

Doc/docs-requirements.txt

@@ -0,0 +1,2 @@
+sphinx == 3.0.2
+sphinx_rtd_theme == 0.4.3

Doc/source/afmLib.rst

@@ -3,5 +3,6 @@ afmLib
 ######
 
 .. automodule:: fontTools.afmLib
+   :inherited-members:
    :members:
    :undoc-members:

Doc/source/agl.rst

@@ -3,5 +3,6 @@ agl
 ###
 
 .. automodule:: fontTools.agl
+   :inherited-members:
    :members:
    :undoc-members:

Doc/source/cffLib.rst → Doc/source/cffLib/index.rst

@@ -2,6 +2,13 @@
 cffLib
 ######
 
+.. toctree::
+   :maxdepth: 1
+
+   specializer
+   width
+
 .. automodule:: fontTools.cffLib
+   :inherited-members:
    :members:
    :undoc-members:

Doc/source/cffLib/specializer.rst

@@ -0,0 +1,8 @@
+###########
+specializer
+###########
+
+.. automodule:: fontTools.cffLib.specializer
+   :inherited-members:
+   :members:
+   :undoc-members:

Doc/source/cffLib/width.rst

@@ -0,0 +1,8 @@
+#####
+width
+#####
+
+.. automodule:: fontTools.cffLib.width
+   :inherited-members:
+   :members:
+   :undoc-members:

Doc/source/colorLib/builder.rst

@@ -0,0 +1,8 @@
+#######
+builder
+#######
+
+.. automodule:: fontTools.colorLib.builder
+   :inherited-members:
+   :members:
+   :undoc-members:

Doc/source/colorLib/errors.rst

@@ -0,0 +1,8 @@
+######
+errors
+######
+
+.. automodule:: fontTools.colorLib.errors
+   :inherited-members:
+   :members:
+   :undoc-members:

Doc/source/colorLib/index.rst

@@ -0,0 +1,14 @@
+########
+colorLib
+########
+
+.. toctree::
+   :maxdepth: 1
+
+   builder
+   errors
+
+.. automodule:: fontTools.colorLib
+   :inherited-members:
+   :members:
+   :undoc-members:

Doc/source/conf.py

@@ -25,40 +25,43 @@
 
 # If your documentation needs a minimal Sphinx version, state it here.
 #
-needs_sphinx = '1.3'
+needs_sphinx = "1.3"
 
 # 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.viewcode']
+extensions = ["sphinx.ext.autodoc", "sphinx.ext.viewcode", "sphinx.ext.napoleon"]
 
-autodoc_mock_imports = ['gtk']
+autodoc_mock_imports = ["gtk"]
 
 # Add any paths that contain templates here, relative to this directory.
-templates_path = ['_templates']
+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'
+source_suffix = ".rst"
 
 # The master toctree document.
-master_doc = 'index'
+master_doc = "index"
 
 # General information about the project.
-project = u'fontTools'
-copyright = u'2017, Just van Rossum, Behdad Esfahbod et al.'
-author = u'Just van Rossum, Behdad Esfahbod et al.'
+project = u"fontTools"
+copyright = u"2020, Just van Rossum, Behdad Esfahbod, and the fontTools Authors. CC BY-SA 4.0"
+author = u"Just van Rossum, Behdad Esfahbod, and the fontTools Authors"
+
+# HTML page title
+html_title = "fontTools Documentation"
 
 # 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'3.10'
+version = u"4.0"
 # The full version, including alpha/beta/rc tags.
-release = u'3.10'
+release = u"4.0"
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
@@ -73,35 +76,41 @@
 exclude_patterns = []
 
 # The name of the Pygments (syntax highlighting) style to use.
-pygments_style = 'sphinx'
+# pygments_style = "sphinx" (the default sphinx docs style on RTD)
+pygments_style = "default"
 
 # If true, `todo` and `todoList` produce output, else they produce nothing.
-todo_include_todos = False
+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 = 'classic'
+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 = {}
+html_theme_options = {"display_version": False}
 
 # 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']
+html_static_path = ["_static"]
+
+html_favicon = "assets/img/favicon.ico"
+
+# display the Sphinx attribution in the footer
+html_show_sphinx = False
 
 
 # -- Options for HTMLHelp output ------------------------------------------
 
 # Output file base name for HTML help builder.
-htmlhelp_basename = 'fontToolsDoc'
+htmlhelp_basename = "fontToolsDoc"
 
 
 # -- Options for LaTeX output ---------------------------------------------
@@ -110,15 +119,12 @@
     # 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',
@@ -128,19 +134,21 @@
 # (source start file, target name, title,
 #  author, documentclass [howto, manual, or own class]).
 latex_documents = [
-    (master_doc, 'fontTools.tex', u'fontTools Documentation',
-     u'Just van Rossum, Behdad Esfahbod et al.', 'manual'),
+    (
+        master_doc,
+        "fontTools.tex",
+        u"fontTools Documentation",
+        u"Just van Rossum, Behdad Esfahbod et al.",
+        "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, 'fonttools', u'fontTools Documentation',
-     [author], 1)
-]
+man_pages = [(master_doc, "fonttools", u"fontTools Documentation", [author], 1)]
 
 
 # -- Options for Texinfo output -------------------------------------------
@@ -149,8 +157,13 @@
 # (source start file, target name, title, author,
 #  dir menu entry, description, category)
 texinfo_documents = [
-    (master_doc, 'fontTools', u'fontTools Documentation',
-     author, 'fontTools', 'A library for manipulating fonts, written in Python.',
-     'Typography'),
+    (
+        master_doc,
+        "fontTools",
+        u"fontTools Documentation",
+        author,
+        "fontTools",
+        "A library for manipulating fonts, written in Python.",
+        "Typography",
+    )
 ]
-