diff --git a/example_docs/api_example/inline_classes.py b/example_docs/api_example/inline_classes.py new file mode 100644 index 00000000..da940d5f --- /dev/null +++ b/example_docs/api_example/inline_classes.py @@ -0,0 +1,51 @@ +from __future__ import annotations + + +class SimpleInlineClass: + """This is a simple class that does not have + any methods or attributes. + + It only has the class description and constructor. + Many classes in Qiskit docs are simple like this. + """ + + def __init__(self, arg1: str) -> None: + self.arg1 = arg1 + + +class InlineClassWithMethods: + """This class is more involved. + + Note how the methods and attributes are rendered and + indented when this class is inlined on the docs page. + """ + + CLASS_ATTRIBUTE: str = "An important part of any API." + + @property + def interest_rate(self): + pass + + def method1(self) -> int: + """A simple method.""" + return 0 + + def method2( + self, arg1: int | float, arg2: list[InlineClassWithMethods], description: str + ) -> tuple[int, InlineClassWithMethods]: + """A method with a lot of args! + + This method will use a Hamiltonian to reach quantum advantage. Hamilton: great play & the + secret to quantum computing. What a polymath. + + Args: + arg1: All numbers accepted. + arg2: A list of other instances, although these will be discarded. + description: If your description is too boring or too cryptic, this program + will crash your computer. + """ + return [0, self] + + +class CustomException(Exception): + """See how exceptions render too.""" diff --git a/example_docs/docs/index.rst b/example_docs/docs/index.rst index 01621756..d23fc817 100644 --- a/example_docs/docs/index.rst +++ b/example_docs/docs/index.rst @@ -20,6 +20,7 @@ A site to test out styling for qiskit-sphinx-theme. :maxdepth: 2 Autodoc + Inline classes .. toctree:: :caption: Special elements diff --git a/example_docs/docs/sphinx_guide/inline_classes.rst b/example_docs/docs/sphinx_guide/inline_classes.rst new file mode 100644 index 00000000..dddc96b0 --- /dev/null +++ b/example_docs/docs/sphinx_guide/inline_classes.rst @@ -0,0 +1,49 @@ +============== +Inline classes +============== + +This is a page to test out how we render classes and functions +included inline in the page. This is common with module pages. + + +Important APIs +============== + +Every time you use this program, you'll want to create an instance of +:class:`api_example.inline_classes.SimpleInlineClass`. It has a simple interface: + +.. autoclass:: api_example.inline_classes.SimpleInlineClass + +It can be useful to use free functions rather than the class: + +.. autofunction:: api_example.my_function + :noindex: + +Sometimes, you even need to use a really complex class! + +.. autoclass:: api_example.inline_classes.InlineClassWithMethods + :no-members: + :show-inheritance: + + .. rubric:: Attributes + + .. autoattribute:: CLASS_ATTRIBUTE + .. autoattribute:: interest_rate + + .. rubric:: Methods + + .. automethod:: method1 + .. automethod:: method2 + + +Warning: exceptions +------------------- + +The above APIs might raise an exception! Be careful! + +.. autoexception:: api_example.inline_classes.CustomException + +Other prose +=========== + +Blah blah blah. \ No newline at end of file diff --git a/tests/js/tests.js b/tests/js/tests.js index d07d0d6c..f2510fde 100644 --- a/tests/js/tests.js +++ b/tests/js/tests.js @@ -85,6 +85,12 @@ test.describe("api docs", () => { const content = page.locator("div.article-container"); await expect(content).toHaveScreenshot(); }); + + test("inline classes", async ({ page }) => { + await page.goto("sphinx_guide/inline_classes.html"); + const content = page.locator("div.article-container"); + await expect(content).toHaveScreenshot(); + }); }); test("tables align with qiskit.", async ({ page }) => { diff --git a/tests/js/tests.js-snapshots/api-docs-inline-classes-1-linux.png b/tests/js/tests.js-snapshots/api-docs-inline-classes-1-linux.png new file mode 100644 index 00000000..3ece913e Binary files /dev/null and b/tests/js/tests.js-snapshots/api-docs-inline-classes-1-linux.png differ diff --git a/tests/js/tests.js-snapshots/inline-table-of-contents-have-correct-fonts-1-linux.png b/tests/js/tests.js-snapshots/inline-table-of-contents-have-correct-fonts-1-linux.png index da3c497b..1cf374a1 100644 Binary files a/tests/js/tests.js-snapshots/inline-table-of-contents-have-correct-fonts-1-linux.png and b/tests/js/tests.js-snapshots/inline-table-of-contents-have-correct-fonts-1-linux.png differ diff --git a/tests/js/tests.js-snapshots/left-side-bar-renders-correctly-1-linux.png b/tests/js/tests.js-snapshots/left-side-bar-renders-correctly-1-linux.png index 2bb81a34..87a1699d 100644 Binary files a/tests/js/tests.js-snapshots/left-side-bar-renders-correctly-1-linux.png and b/tests/js/tests.js-snapshots/left-side-bar-renders-correctly-1-linux.png differ