Merge pull request #6 from aaliddell/dev

1.5.0 Release

.flake8

@@ -1,4 +1,20 @@
 [flake8]
 max-line-length = 100
-ignore = E261,E501,E731,W503
+ignore =
+    # Ignore line break before binary operator
+    W503,
+per-file-ignores =
+    __init__.py:
+        # Ignore unused imports in __init__.py files
+        F401,
+        # Ignore 'from module import *' in __init__.py files
+        F403,
+    test_*.py:
+        # Ignore line too long in tests
+        E501,
+        # Ignore pydocstyle in tests
+        D100,D101,D102,D103
+    conftest.py:
+        # Ignore line too long in tests setup
+        E501,
 exclude = .ipynb_checkpoints

.github/workflows/ci.yml

@@ -15,7 +15,7 @@ jobs:
     strategy:
       matrix:
         os: [macos-latest, ubuntu-latest, windows-latest]
-        python-version: [3.6, 3.7, 3.8, 3.9]
+        python-version: [3.6, 3.7, 3.8, 3.9, '3.10']
 
     steps:
       - uses: actions/checkout@v2
@@ -45,38 +45,3 @@ jobs:
         run: nox -s pylint
       - name: Run pydocstyle
         run: nox -s pydocstyle
-
-  docs:
-    name: Build and push docs
-    runs-on: ubuntu-latest
-    if: github.ref == 'refs/heads/main'
-    steps:
-      - uses: actions/checkout@v2
-        with:
-          fetch-depth: 0  # To fetch all refs
-      - name: Set up Python
-        uses: actions/setup-python@v1
-        with:
-          python-version: 3.8
-      - name: Install nox
-        run: pip install nox
-      - name: Build docs
-        run: nox -s docs -- -d /tmp/sphinx-doctrees
-      - name: Copy built docs and checkout
-        run: |
-          rm -rf __pycache__ **/__pycache__ .doctrees **/.doctrees .buildinfo **/.buildinfo
-          cp -r docs/build /tmp/sphinx-build
-          git clean -fx
-          git checkout gh-pages
-          git rm -r .  # Clean branch to ensure removed files don't persist
-      - name: Commit and push docs
-        env:
-          GIT_WORK_TREE: /tmp/sphinx-build
-        run: |
-          git status
-          git add .
-          git status
-          git config --global user.name "${GITHUB_ACTOR}"
-          git config --global user.email "${GITHUB_ACTOR}@users.noreply.github.com"
-          git commit --allow-empty --message "Update docs to ${GITHUB_SHA} from ${GITHUB_REF}"
-          git push

.gitignore

@@ -85,4 +85,4 @@ dmypy.json
 /docs/build
 
 # Autogenerated API docs
-/docs/source/api
+/docs/api

.readthedocs.yaml

@@ -0,0 +1,10 @@
+version: 2
+sphinx:
+  configuration: docs/conf.py
+python:
+  version: 3.7
+  install:
+    - method: pip
+      path: .
+      extra_requirements:
+        - dev

README.rst

@@ -17,6 +17,10 @@ library.
    :alt: CI Status
    :target: https://github.com/aaliddell/s2cell/actions
 
+.. image:: https://readthedocs.org/projects/s2cell/badge/?version=latest
+   :alt: Documentation Status
+   :target: https://docs.s2cell.aliddell.com/en/latest
+
 .. image:: https://img.shields.io/github/license/aaliddell/s2cell
    :alt: License
    :target: https://github.com/aaliddell/s2cell

docs/source/annotated_source.rst → docs/annotated_source.rst

@@ -13,6 +13,6 @@ system that are useful for understanding the steps to convert from one represent
 The full source of the library is included below.
 
 
-.. literalinclude:: ../../s2cell/__init__.py
+.. literalinclude:: ../s2cell/s2cell.py
    :language: python3
-   :lines: 25-
+   :lines: 22-

docs/source/changelog.rst → docs/changelog.rst

@@ -5,6 +5,14 @@
 Changelog
 =========
 
+1.5.0
+-----
+
+- Moved main source out of ``__init__.py``
+- Moved docs hosting to Read the Docs
+- Updated docs to improve readability
+
+
 1.4.0
 -----
 

docs/conf.py

@@ -1,4 +1,5 @@
 import datetime
+import os
 
 # -- Project information -----------------------------------------------------
 
@@ -20,80 +21,109 @@
 extensions = [
     # Internal
     'sphinx.ext.autodoc',
-    'sphinx.ext.githubpages',
     'sphinx.ext.napoleon',
 
     # External
+    'notfound.extension',
     'sphinx_sitemap',
 ]
 
 # Add any paths that contain templates here, relative to this directory.
-templates_path = []
+templates_path = ['templates']
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
 # This pattern also affects html_static_path and html_extra_path.
-exclude_patterns = ['.ipynb_checkpoints', '**/.ipynb_checkpoints']
+exclude_patterns = ['.ipynb_checkpoints', '**/.ipynb_checkpoints', 'api/s2cell.rst']
 
 # Code highlighting
 pygments_style = 'monokai'
 
 # Enable figure numbering
 numfig = True
 
+# Setup root doc
+root_doc = 'index'
+
+
+# -- Run sphinx-apidoc -------------------------------------------------------
+
+def run_apidoc(_):
+    import sphinx.ext.apidoc
+
+    docs_path = os.path.dirname(__file__)
+    apidoc_path = os.path.join(docs_path, 'api')
+    module_path = os.path.join(docs_path, '..', 's2cell')
+
+    sphinx.ext.apidoc.main([
+        '--no-toc',
+        '--force',
+        '--separate',
+        '-o', apidoc_path,
+        module_path
+    ])
+
+
+def setup(app):
+    app.connect('builder-inited', run_apidoc)
+
 
 # -- Options for HTML output -------------------------------------------------
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #
-import sphinx_redactor_theme
-html_theme = 'sphinx_redactor_theme'
-html_theme_path = [sphinx_redactor_theme.get_html_theme_path()]
+html_theme = 'furo'
+
+# Title
+html_title = 's2cell'
 
 # Logo and favicon
-html_logo = 'source/_static/logo.min.svg'
-html_favicon = 'source/_static/logo-64.png'
+html_logo = 'static/logo.min.svg'
+html_favicon = 'static/logo-64.png'
 
 # Base URL for docs
-# Used to generate CNAME file
 html_baseurl = 'https://docs.s2cell.aliddell.com'
 
 # Extra vars to provide to templating
 html_context = {
     'baseurl': html_baseurl,
-    'icon_png': 'logo.png'
+    'icon_png': 'logo.png',
+    'absolute_icon_png': html_baseurl + '/en/latest/_static/logo.png'  # Used by meta tags
 }
 
 # 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 = ['source/_static']
+html_static_path = ['static']
 
 # Theme options
 html_theme_options = {
-    'display_version': True,
+    'sidebar_hide_name': True,
+    'light_css_variables': {
+        'color-brand-primary': '#de6b00',
+        'color-brand-content': '#de6b00',
+    },
+    'dark_css_variables': {
+        'color-brand-primary': '#de6b00',
+        'color-brand-content': '#de6b00',
+    },
 }
 
 # Disable footer
 html_show_sphinx = False
 
-# Template overrides
-templates_path = ['_templates']
-
 # Add CSS files
-html_css_files = [
-    'pygments.css',  # Manually add pygments.css, since sphinx_redactor_theme does not
-    'customise.css',
-]
+html_css_files = []
 
 # Extra files to include
 html_extra_path = [
-    'source/robots.txt',
+    'robots.txt',
 ]
 
 # Sitemap options
-sitemap_url_scheme = '{lang}{link}'
+sitemap_filename = "sitemap-override.xml"  # RTD generates sitemap with not much in it...
+sitemap_url_scheme = "{link}"
 
 # -- Options for autodoc -----------------------------------------------------
 

docs/source/index.rst → docs/index.rst

@@ -2,15 +2,15 @@
 :description: Minimal Python S2 cell ID, S2 token and lat/lon conversion library
 :keywords: S2, S2 Geometry, s2cell, S2 cell, cell ID, S2 token, token, Python
 
-.. include:: ../../README.rst
+.. include:: ../README.rst
 
 
 .. toctree::
    :hidden:
 
    Overview <self>
-   s2_concepts
-   API Reference <api/s2cell>
-   useful_s2_links
+   Concepts <s2_concepts>
+   API Reference <api/s2cell.s2cell>
+   Useful Links <useful_s2_links>
    annotated_source
    changelog

docs/source/s2_concepts.rst → docs/s2_concepts.rst

@@ -34,7 +34,7 @@ position generally become close in 2D space).
 
 .. _fig_hilbert:
 
-.. figure:: _static/hilbert.svg
+.. figure:: static/hilbert.svg
    :height: 200px
    :alt: Hilbert Curve Steps 1, 2 and 3 (Qef, Public domain, via Wikimedia Commons)
    :align: center
@@ -144,7 +144,7 @@ the base Hilbert Curve.
 
 .. _fig_cube_unwrapped:
 
-.. figure:: _static/cube_unwrapped.svg
+.. figure:: static/cube_unwrapped.svg
    :alt: Cube face mapping
    :align: center
 
@@ -170,7 +170,7 @@ cube.
 
 .. _fig_uv_face_0:
 
-.. figure:: _static/uv_face_0.svg
+.. figure:: static/uv_face_0.svg
    :alt: Face 0 in UV coordinates
    :align: center
 
@@ -207,15 +207,15 @@ projection. :numref:`fig_st_face_0` shows the ST mapping of the same region as s
 
 .. _fig_uv_to_st_projections:
 
-.. figure:: _static/uv_to_st_projections.svg
+.. figure:: static/uv_to_st_projections.svg
    :alt: The three UV to ST projections provided in the reference S2 implementation
    :align: center
 
    The three UV to ST projections provided in the reference S2 implementation
 
 .. _fig_st_face_0:
 
-.. figure:: _static/st_face_0.svg
+.. figure:: static/st_face_0.svg
    :alt: Face 0 in ST coordinates
    :align: center