Use Furo theme for documentation (#12348)

97littleleaf11 · web-flow · commit fec532028dcb · 2022-03-24T14:39:19.000Z
Current readthedoc theme cannot fully utilize the width of browser especially when you are using a wide screen. I am choosing Furo since it's quite popular in python community (pip, black, etc). Other changes: * Use mypy instead of Mypy * Move introduction to index page, which makes better impression for newcomers. Closes #12374
diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
@@ -7,6 +7,7 @@ on:
   pull_request:
     paths:
     - 'docs/**'
+    - 'mypyc/doc/**'
     - '**/*.rst'
     - '**/*.md'
     - CREDITS
@@ -21,7 +22,7 @@ jobs:
       - uses: actions/checkout@v2
       - uses: actions/setup-python@v2
         with:
-          python-version: '3.7'
+          python-version: '3.10'
       - name: Install tox
         run: pip install --upgrade 'setuptools!=50' 'virtualenv>=20.6.0' tox==3.24.5
       - name: Setup tox environment
diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml
@@ -7,6 +7,7 @@ on:
   pull_request:
     paths-ignore:
     - 'docs/**'
+    - 'mypyc/doc/**'
     - '**/*.rst'
     - '**/*.md'
     - .gitignore
diff --git a/docs/requirements-docs.txt b/docs/requirements-docs.txt
@@ -1,2 +1,2 @@
 sphinx>=4.2.0,<5.0.0
-sphinx-rtd-theme>=1.0.0,<2.0.0
+furo>=2022.3.4
diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -48,8 +48,8 @@
 master_doc = 'index'
 
 # General information about the project.
-project = u'Mypy'
-copyright = u'2016, Jukka Lehtosalo'
+project = u'mypy'
+copyright = u'2012-2022 Jukka Lehtosalo and mypy contributors'
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
@@ -103,13 +103,7 @@
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
-try:
-    import sphinx_rtd_theme
-except:
-    html_theme = 'default'
-else:
-    html_theme = 'sphinx_rtd_theme'
-    html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
+html_theme = "furo"
 
 # 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
@@ -128,7 +122,7 @@
 
 # The name of an image file (relative to this directory) to place at the top
 # of the sidebar.
-#html_logo = None
+html_logo = "http://mypy-lang.org/static/mypy_light.svg"
 
 # The name of an image file (within the static path) to use as favicon of the
 # docs.  This file should be a Windows icon file (.ico) being 16x16 or 32x32
@@ -187,7 +181,7 @@
 #html_file_suffix = None
 
 # Output file base name for HTML help builder.
-htmlhelp_basename = 'Mypydoc'
+htmlhelp_basename = 'mypydoc'
 
 
 # -- Options for LaTeX output ---------------------------------------------
diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -6,13 +6,43 @@
 Welcome to mypy documentation!
 ==============================
 
-Mypy is a static type checker for Python 3 and Python 2.7.
+Mypy is a static type checker for Python 3 and Python 2.7. If you sprinkle
+your code with type annotations, mypy can type check your code and find common
+bugs. As mypy is a static analyzer, or a lint-like tool, the type
+annotations are just hints for mypy and don't interfere when running your program.
+You run your program with a standard Python interpreter, and the annotations
+are treated effectively as comments.
+
+Using the Python 3 annotation syntax (using :pep:`484` and :pep:`526` notation)
+or a comment-based annotation syntax for Python 2 code, you will be able to
+efficiently annotate your code and use mypy to check the code for common errors.
+Mypy has a powerful and easy-to-use type system with modern features such as
+type inference, generics, callable types, tuple types, union types, and
+structural subtyping.
+
+As a developer, you decide how to use mypy in your workflow. You can always
+escape to dynamic typing as mypy's approach to static typing doesn't restrict
+what you can do in your programs. Using mypy will make your programs easier to
+understand, debug, and maintain.
+
+This documentation provides a short introduction to mypy. It will help you
+get started writing statically typed code. Knowledge of Python and a
+statically typed object-oriented language, such as Java, are assumed.
+
+.. note::
+
+   Mypy is used in production by many companies and projects, but mypy is
+   officially beta software. There will be occasional changes
+   that break backward compatibility. The mypy development team tries to
+   minimize the impact of changes to user code.
+
+Contents
+--------
 
 .. toctree::
    :maxdepth: 2
    :caption: First steps
 
-   introduction
    getting_started
    existing_code
 
@@ -74,6 +104,13 @@ Mypy is a static type checker for Python 3 and Python 2.7.
    additional_features
    faq
 
+.. toctree::
+   :hidden:
+   :caption: Project Links
+
+   GitHub <https://github.com/python/mypy>
+   Website <http://mypy-lang.org/>
+
 Indices and tables
 ==================
 
diff --git a/docs/source/introduction.rst b/docs/source/introduction.rst
diff --git a/mypyc/doc/conf.py b/mypyc/doc/conf.py
@@ -17,7 +17,7 @@
 # -- Project information -----------------------------------------------------
 
 project = 'mypyc'
-copyright = '2020, mypyc team'
+copyright = '2020-2022, mypyc team'
 author = 'mypyc team'
 
 # The version info for the project you're documenting, acts as replacement for
@@ -50,13 +50,7 @@
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
-try:
-    import sphinx_rtd_theme  # type: ignore
-except:
-    html_theme = 'default'
-else:
-    html_theme = 'sphinx_rtd_theme'
-    html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
+html_theme = 'furo'
 
 # 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,
diff --git a/mypyc/doc/index.rst b/mypyc/doc/index.rst
@@ -47,6 +47,12 @@ generate fast code.
 
    performance_tips_and_tricks
 
+.. toctree::
+   :hidden:
+   :caption: Project Links
+
+   GitHub <https://github.com/python/mypy>
+
 Indices and tables
 ==================
 

Original file line number	Diff line number	Diff line change
`@@ -1,2 +1,2 @@`
`1`	`1`	`sphinx>=4.2.0,<5.0.0`
`2`		`-sphinx-rtd-theme>=1.0.0,<2.0.0`
	`2`	`+furo>=2022.3.4`