Fix inline class example (#605)

Turns out, none of the inline classes from Qiskit SDK use the rubric
like this to set Attributes and Methods. It's a bad example.

We also:

* Add an index page for API docs
* Classify inline_classes as a module page, rather than freeform. This
fixes an assumption with qiskit/documentation

example_docs/api_example/inline_classes.py

@@ -1,3 +1,50 @@
+"""
+==============
+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.inline_classes.inline_function
+
+Sometimes, you even need to use a really complex class!
+
+.. autoclass:: api_example.inline_classes.InlineClassWithMethods
+   :no-members:
+   :show-inheritance:
+
+   .. autoattribute:: CLASS_ATTRIBUTE
+   .. autoattribute:: interest_rate
+
+   .. 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.
+"""
+
 from __future__ import annotations
 
 
@@ -49,3 +96,11 @@ def method2(
 
 class CustomException(Exception):
     """See how exceptions render too."""
+
+
+def inline_function(input1: str, input2: str) -> int:
+    """A function that does awesome stuff.
+
+    Returns:
+        Did the function work.
+    """

example_docs/docs/apidoc/index.rst

@@ -0,0 +1,9 @@
+=============
+API reference
+=============
+
+.. toctree::
+   :maxdepth: 1
+
+   module
+   inline_classes

example_docs/docs/apidoc/inline_classes.rst

@@ -1,49 +1,6 @@
-==============
-Inline classes
-==============
+.. _api-example.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
+.. automodule:: api_example.inline_classes
    :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-inherited-members:
+   :no-special-members:

example_docs/docs/index.rst

@@ -14,13 +14,7 @@ A site to test out styling for qiskit-sphinx-theme.
    sphinx_guide/images
    sphinx_guide/paragraph
    sphinx_guide/structural
-
-.. toctree::
-  :caption: API
-  :maxdepth: 2
-
-   Autodoc <apidoc/module>
-   Inline classes <apidoc/inline_classes>
+   API Reference <apidoc/index>
 
 .. toctree::
    :caption: Special elements