Fix docs and use furo (globus#713)

* Fix docs and switch to furo - Add a makefile - make lint is pre-commit, make docs builds a venv - `make doc` build installs packages and sphinx requirements - Fix image config to use a `_static/` dir and be consistent * add light and dark, cropped and normal logos (globus#652) * Cleanup and fix a plethora of doc warnings - Remove useless autogenerated "stubs" - Create autoclass docs for a small number of classes - Move `FuncXExecutor` to a top-level importable member of `funcx` and note this in the changelog - Remove nbsphinx from docs extra (unused) - Cut down on sphinx extensions to the essentials - Fix many warnings throughout the docs Co-authored-by: Kirill Nagaitsev <[email protected]>
slateci · Mar 9, 2022 · 28182fc · 28182fc
1 parent 34076e7
commit 28182fc
Show file tree

Hide file tree

Showing 47 changed files with 87 additions and 570 deletions.
diff --git a/.gitmodules b/.gitmodules
@@ -1,4 +0,0 @@
-[submodule "docs/examples"]
-	path = docs/examples
-	url = https://github.com/funcx-faas/examples
-	branch = main

diff --git a/Makefile b/Makefile
@@ -3,7 +3,9 @@
 	.venv-docs/bin/pip install -U pip setuptools
 	.venv-docs/bin/pip install './funcx_sdk[docs]' './funcx_endpoint'
 
-.PHONY: docs
+.PHONY: lint docs
+lint:
+	pre-commit run -a
 docs: .venv-docs
 	# clean the build dir before rebuilding
 	cd docs; rm -rf _build/

diff --git a/changelog.d/20220308_233538_sirosen_furo_docs.rst b/changelog.d/20220308_233538_sirosen_furo_docs.rst
@@ -0,0 +1,5 @@
+Changed
+^^^^^^^
+
+- ``FuncXExeuctor`` is now importable from the top-level namespace, as in
+  ``from funcx import FuncXExecutor``
diff --git a/docs/Tutorial.rst b/docs/Tutorial.rst
@@ -80,7 +80,10 @@ Functions with Arguments
 
 funcX supports registration and invocation of functions with arbitrary arguments and returned parameters.
 funcX will serialize any ``*args`` and ``**kwargs`` when invoking a function and it will serialize any return parameters or exceptions.
- Note: funcX uses standard Python serilaization libraries (e.g., Pickle, Dill) it also limits the size of input arguments and returned parameters to 5MB.
+
+.. note::
+
+    funcX uses standard Python serilaization libraries (e.g., Pickle, Dill) it also limits the size of input arguments and returned parameters to 5MB.
 
 The following example shows a function that computes the sum of a list of input arguments.
 First we register the function as above.

diff --git a/docs/_static/images/funcX-dark-cropped.png b/docs/_static/images/funcX-dark-cropped.png
diff --git a/docs/_static/images/funcX-dark.png b/docs/_static/images/funcX-dark.png
diff --git a/docs/_static/images/funcX-light-cropped.png b/docs/_static/images/funcX-light-cropped.png
diff --git a/docs/_static/images/funcX-light.png b/docs/_static/images/funcX-light.png
diff --git a/docs/changelog.rst b/docs/changelog.rst
@@ -6,8 +6,8 @@ Changelog
 funcx & funcx-endpoint v0.3.7
 -----------------------------
 
- Bug Fixes
- ^^^^^^^^^
+Bug Fixes
+^^^^^^^^^
 
 - When a provider raised an exception, that exception was then mishandled
   and presented as an AttributeError. This handling now no longer corrupts
@@ -483,7 +483,8 @@ New Functionality
   * funcx-endpoint connects to a forwarder service over an encrypted (Curve25519 elliptic curve) ZMQ channel using the server certificates.
   * If the connection is terminated this whole process repeats.
 
-* Significant changes to the `Config object`. All options related to executors have been moved from the top level Config object to the executor object. Refer to the `configuration <configuration> section for more details. Here's an example of the config change:
+* Significant changes to the `Config object`. All options related to executors have been moved from the top level Config object to the executor object.
+  Refer to the `configuration <configuration>`_ section for more details. Here's an example of the config change:
 
     This is the old style config:
 
@@ -542,30 +543,30 @@ New Functionality
     .. code-block:: json
 
         {
-          'status': 'Success',
-          'task_uuids': ['task_id_1', 'task_id_2', ...]
+          "status": "Success",
+          "task_uuids": ["task_id_1", "task_id_2", "..."]
         }
 
     This is the new response format, where some task submissions have failed:
 
     .. code-block:: json
 
         {
-          'response': 'batch',
-          'results': [
+          "response": "batch",
+          "results": [
             {
-              'status': 'Success',
-              'task_uuid': 'task_id_1',
-              'http_status_code': 200
+              "status": "Success",
+              "task_uuid": "task_id_1",
+              "http_status_code": 200
             },
             {
-              'status': 'Failed',
-              'code': 1,
-              'task_uuid': 'task_id_2',
-              'http_status_code': 4XX/5XX,
-              'error_args': [...]
+              "status": "Failed",
+              "code": 1,
+              "task_uuid": "task_id_2",
+              "http_status_code": 400,
+              "error_args": ["..."]
             },
-            ...
+            "..."
           ]
         }
 

diff --git a/docs/conf.py b/docs/conf.py
@@ -23,15 +23,10 @@
 # ones.
 extensions = [
     "sphinx.ext.autodoc",
-    "sphinx.ext.autosummary",
     "sphinx.ext.intersphinx",
-    # 'sphinx.ext.linkcode',
     "sphinx.ext.napoleon",
-    "sphinx.ext.autosectionlabel",
 ]
 
-autosummary_generate = True
-
 intersphinx_mapping = {
     "python": ("https://docs.python.org/3", None),
 }
@@ -42,8 +37,12 @@
 exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
 
 # theming, styles, and color options
-pygments_style = "sphinx"
-html_theme = "sphinx_rtd_theme"
+pygments_style = "friendly"
+pygments_dark_style = "monokai"  # this is a furo-specific option
+html_show_sourcelink = True
+html_theme = "furo"
 html_static_path = ["_static"]
-# disabled logo for now -- it looks bad on the RTD theme
-# html_logo = "_static/logo.png"
+html_theme_options = {
+    "light_logo": "images/funcX-light-cropped.png",
+    "dark_logo": "images/funcX-dark-cropped.png",
+}
diff --git a/docs/configuring.rst b/docs/configuring.rst
@@ -94,7 +94,7 @@ using the `CobaltProvider`. This configuration assumes that the script is being
 
 
 Polaris (ALCF)
-^^^^^^^^^^^^^
+^^^^^^^^^^^^^^
 
 .. image:: images/ALCF_Polaris.jpeg
 

diff --git a/docs/endpoints.rst b/docs/endpoints.rst
@@ -87,8 +87,10 @@ Once started, the endpoint uses a daemon process to run in the background.
 
 .. note:: If the endpoint was not stopped correctly previously (e.g., after a computer restart when the endpoint was running), the endpoint directory will be cleaned up to allow a fresh start
 
-.. warning:: Only the owner of an endpoint is authorized to start an endpoint. Thus if you register an endpoint
-using one identity and try to start an endpoint owned by another identity, it will fail.
+.. warning::
+
+    Only the owner of an endpoint is authorized to start an endpoint. Thus if you register an endpoint
+    using one identity and try to start an endpoint owned by another identity, it will fail.
 
 
 Stopping an Endpoint

diff --git a/docs/examples b/docs/examples
diff --git a/docs/executor.rst b/docs/executor.rst
@@ -13,8 +13,7 @@ Initializing the executor
 
 .. code-block:: python
 
-   from funcx import FuncXClient
-   from funcx.sdk.executor import FuncXExecutor
+   from funcx import FuncXClient, FuncXExecutor
 
    fx = FuncXExecutor(FuncXClient())
 

diff --git a/docs/index.rst b/docs/index.rst
@@ -88,11 +88,12 @@ how to download and configure an endpoint for local (multi-process) execution. :
    :caption: Contents:
 
    quickstart
+   executor
    sdk
    endpoints
    Tutorial
    actionprovider
-   reference
+   reference/index
    debugging
    limits
    changelog

diff --git a/docs/quickstart.rst b/docs/quickstart.rst
@@ -56,7 +56,7 @@ To update a previously installed funcX to a newer version, use: ``python3 -m pip
 
 
 Running a function
-------------------------
+------------------
 
 After installing the funcX SDK, you can register functions and execute
 them on available endpoints.  To use the SDK, you should first instantiate

diff --git a/docs/reference.rst b/docs/reference.rst
diff --git a/docs/reference/client.rst b/docs/reference/client.rst
@@ -0,0 +1,6 @@
+The FuncX Client
+================
+
+.. autoclass:: funcx.FuncXClient
+    :members:
+    :member-order: bysource
diff --git a/docs/reference/errors.rst b/docs/reference/errors.rst
@@ -0,0 +1,7 @@
+Errors
+======
+
+.. autoclass:: funcx.FuncxAPIError
+    :members:
+    :member-order: bysource
+
diff --git a/docs/reference/executor.rst b/docs/reference/executor.rst
@@ -0,0 +1,7 @@
+The FuncX Executor
+==================
+
+.. autoclass:: funcx.FuncXExecutor
+    :members:
+    :member-order: bysource
+
diff --git a/docs/reference/index.rst b/docs/reference/index.rst
@@ -0,0 +1,10 @@
+.. module:: funcx
+
+funcX SDK
+=========
+
+.. toctree::
+
+    executor
+    client
+    errors
diff --git a/docs/sdk.rst b/docs/sdk.rst
@@ -1,5 +1,5 @@
-SDK
-============
+FuncX SDK User Guide
+====================
 
 The **funcX SDK** provides a programmatic interface to funcX from Python.
 The SDK provides a convenient Pythonic interface to:
@@ -59,6 +59,7 @@ is defined in the same way as any Python function before being registered with f
 
 Running Functions
 -----------------
+
 You can invoke a function using the UUID returned when registering the function. The `run()` function
 requires that you specify the function (`function_id`) and endpoint (`endpoint_id`) on which to execute
 the function. funcX will return a UUID for the executing function (called a task) via which you can
@@ -95,10 +96,12 @@ task is still pending.
 
 Arguments and data
 ------------------
+
 funcX functions operate the same as any other Python function. You can pass arguments \*args and \**kwargs
 and return values from functions. The only constraint is that data passed to/from a funcX function must be
-serializable (e.g., via Pickle) and fall within :ref:`Limits` .  Input arguments can be passed to the function
-using the `run()` function. The following example shows how strings can be passed to and from a function.
+serializable (e.g., via Pickle) and fall within service limits.
+Input arguments can be passed to the function using the `run()` function.
+The following example shows how strings can be passed to and from a function.
 
 .. code-block:: python
 
@@ -195,11 +198,3 @@ and a result if it is available.
    'e453a993-73e6-4149-8078-86e7b8370c35': {'pending': True,
                                             'status': 'waiting-for-ep'}
   }
-
-
-
-FuncXClient Reference:
-----------------------
-
-.. autoclass:: funcx.FuncXClient
-   :members:
diff --git a/docs/stubs/funcx.rst b/docs/stubs/funcx.rst
-Original file line number
+Diff line change
@@ Expand Up @@
     Running a function
-    ------------------------
+    ------------------
     After installing the funcX SDK, you can register functions and execute
     them on available endpoints.  To use the SDK, you should first instantiate
@@ Expand Down @@