From 503728047a9e6eaebebfbbb3afad07eba5f0ff59 Mon Sep 17 00:00:00 2001 From: Stephen Rosen Date: Tue, 8 Jun 2021 18:40:39 +0000 Subject: [PATCH 1/3] Target [source] links more accurately in SASS Because `.viewcode-link` is already marked with `float: right` independently, don't assign that style redundantly when styling `[source]` links attached to function and class defintions. Use `.viewcode-link` instead of `a.reference.internal` to ensure that the styling for `[source]` links is not accidentally applied to return type annotations which are also internal references. --- src/furo/assets/styles/content/_api.sass | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/src/furo/assets/styles/content/_api.sass b/src/furo/assets/styles/content/_api.sass index 81b8ee923..1c4b5b5ec 100644 --- a/src/furo/assets/styles/content/_api.sass +++ b/src/furo/assets/styles/content/_api.sass @@ -55,13 +55,12 @@ dl.exception color: var(--color-api-keyword) padding-right: 0.25rem - // Align the [source] to the right. + // adjust the size of the [source] link on the right. code.sig-name.descname, // final part of named object. span.sig-paren, // final ')' on a method definition > span.pre // return annotation, on a function definition - + a.reference.internal + .viewcode-link width: 3.5rem - float: right font-size: var(--font-size--small) .sig-name @@ -81,7 +80,7 @@ div.versionadded, div.versionchanged, div.deprecated margin-top: 0.125rem margin-bottom: 0.125rem -// Align the [docs] to the right. +// Align the [docs] and [source] to the right. .viewcode-link, .viewcode-back float: right text-align: right From 61a2f5b1645ec5a13b6234a4a6f89fbac90d3820 Mon Sep 17 00:00:00 2001 From: Stephen Rosen Date: Tue, 8 Jun 2021 20:26:25 +0000 Subject: [PATCH 2/3] Add a test case to kitchen-sink for autodoc In conf.py, modify sys.path to add `kitchen_sink/demo_py/` This is the approach taken in the sphinx_rtd_theme in order to add an autodoc'ed module [1]. This module contains a class with one method and a function. This is more than enough to ensure that autodoc with type annotated methods and functions is exercised in furo. [1] https://github.com/readthedocs/sphinx_rtd_theme/blob/671703c3fbb5629fb5004afc941b59310976c28b/docs/conf.py#L10 --- docs/conf.py | 7 +++++ docs/kitchen-sink/autodoc.rst | 9 ++++++ docs/kitchen-sink/demo_py/furo_demo_module.py | 28 +++++++++++++++++++ docs/kitchen-sink/index.md | 1 + 4 files changed, 45 insertions(+) create mode 100644 docs/kitchen-sink/autodoc.rst create mode 100644 docs/kitchen-sink/demo_py/furo_demo_module.py diff --git a/docs/conf.py b/docs/conf.py index af7d36383..526c1ee70 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -3,6 +3,13 @@ # Full list of options can be found in the Sphinx documentation: # https://www.sphinx-doc.org/en/master/usage/configuration.html +import os +import sys + +# add the demo python code to the path, so that it can be used to demonstrate +# source links +sys.path.append(os.path.abspath("./kitchen-sink/demo_py")) + # # -- Project information ----------------------------------------------------- # diff --git a/docs/kitchen-sink/autodoc.rst b/docs/kitchen-sink/autodoc.rst new file mode 100644 index 000000000..73df75e2f --- /dev/null +++ b/docs/kitchen-sink/autodoc.rst @@ -0,0 +1,9 @@ +******* +Autodoc +******* + +This is a run of automodule to grab classes, functions, and members from the +demo module. + +.. automodule:: furo_demo_module + :members: diff --git a/docs/kitchen-sink/demo_py/furo_demo_module.py b/docs/kitchen-sink/demo_py/furo_demo_module.py new file mode 100644 index 000000000..a9c321e89 --- /dev/null +++ b/docs/kitchen-sink/demo_py/furo_demo_module.py @@ -0,0 +1,28 @@ +""" +This is a demo module included in the docs in order to exercise viewcode, +autodoc, and other related functionality. +""" + + +class Foo: + """ + A demo class of type Foo. + + Has a method baz() returning ints. + """ + + def baz(self) -> int: + """ + Return a random integer. + See also: https://xkcd.com/221/ + """ + return 3 + + +def bar(f: Foo) -> Foo: + """ + the identity function, but only for Foos + """ + if isinstance(f, Foo): + return f + raise TypeError("Expected a Foo!") diff --git a/docs/kitchen-sink/index.md b/docs/kitchen-sink/index.md index a07ff4934..483598c64 100644 --- a/docs/kitchen-sink/index.md +++ b/docs/kitchen-sink/index.md @@ -12,4 +12,5 @@ demo lists_tables really-long structure +autodoc ``` From 56dde135821146e9bf6e30685e5ba2463d81295b Mon Sep 17 00:00:00 2001 From: Stephen Rosen Date: Tue, 8 Jun 2021 20:39:59 +0000 Subject: [PATCH 3/3] Fix styling of [source] links Now that the `.viewcode-link` selector is being used, it's not necessary to try to use `+` to find an adjacent element. The prior revision dropped this, but did not remove the selectors for elements neighboring the viewcode-link, resulting in the style not being applied. --- src/furo/assets/styles/content/_api.sass | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/src/furo/assets/styles/content/_api.sass b/src/furo/assets/styles/content/_api.sass index 1c4b5b5ec..b273240a7 100644 --- a/src/furo/assets/styles/content/_api.sass +++ b/src/furo/assets/styles/content/_api.sass @@ -56,9 +56,7 @@ dl.exception padding-right: 0.25rem // adjust the size of the [source] link on the right. - code.sig-name.descname, // final part of named object. - span.sig-paren, // final ')' on a method definition - > span.pre // return annotation, on a function definition + a.reference.internal .viewcode-link width: 3.5rem font-size: var(--font-size--small)