Show Class Attributes For `PSD` And `Spectrogram` In The Docs

Mar 9, 2025 by ADMIN 62 views

Introduction

In the documentation of PSD and Spectrogram classes, it is essential to display the instance attributes for users to understand the properties of these objects. However, the current implementation does not render the class docstrings online, making it challenging for users to access this information. In this article, we will explore a solution to display the class attributes and methods in a clear and organized manner.

Understanding the Issue

The current implementation uses the autoclass_content and autodoc_class_signature settings in the Sphinx conf.py file to render the class docstring and methods. While this works, it displays all the methods, including the __init__() method, which can be overwhelming for users. Ideally, we would like to have clear sections for Attributes and Methods.

Modifying the Theme HTML

To achieve this, we need to modify the theme HTML to render the section headings correctly. By default, Sphinx uses the autodoc_class_signature setting to render the class signature, which includes the section headings. However, this setting does not allow us to customize the section headings.

To fix this issue, we can create a custom theme HTML file that overrides the default behavior. We can use the autoclass_content setting to render the class docstring and then use the autodoc_class_signature setting to render the methods.

Customizing the Class Docstring

To display the class attributes, we need to customize the class docstring to include a section heading for Attributes. We can use the autoclass_content setting to render the class docstring and then use the autodoc_class_signature setting to render the methods.

Here is an example of how we can customize the class docstring:

class PSD:
    """A class for calculating and plotting PSDs of one or more waveforms.

    **Attributes**
    ------------

    * `method` (str): See :meth:`__init__`
    * `win_dur` (int or float): See :meth:`__init__`; only defined if ``method='welch'``

    **Methods**
    -----------

    * `__init__`: Initializes the PSD object
    * `calculate`: Calculates the PSD of one or more waveforms
    * `plot`: Plots the PSD of one or more waveforms
    """

In this example, we have added a section heading for Attributes and listed the instance attributes. We have also added a section heading for Methods and listed the methods.

Customizing the Theme HTML

To render the section headings correctly, we need to modify the theme HTML file. We can create a custom theme HTML file that overrides the default behavior.

Here is an example of how we can modify the theme HTML file:

<!-- custom_theme.html -->

<!-- ... -->

<div class="autoclass-content">
    <h2>Attributes</h2>
    <ul>
        {% for attr in class_attrs %}
        <li>{{ attr }}</li>
        {% endfor %}
    </ul>
</div>

<div class="autodoc-class-signature">
    <h2>Methods</h2>
    <ul>
        {% for method in class_methods %}
        <li>{{ method }}</li>
        {% endfor %}
    </ul>
</div>

<!-- ... -->

In this example, we have added a custom section heading for Attributes and Methods. We have also listed the instance attributes and methods.

Conclusion

In this article, we have explored a solution to display the class attributes and methods in a clear and organized manner. We have customized the class docstring to include section headings for Attributes and Methods and modified the theme HTML file to render the section headings correctly. By following these steps, we can provide users with a clear understanding of the properties and methods of the PSD and Spectrogram classes.

Customizing the Sphinx Configuration

To apply the custom theme HTML file, we need to modify the Sphinx configuration file. We can add the following lines to the conf.py file:

import os

# ...

# Custom theme HTML file
html_theme_path = [os.path.join(os.path.dirname(__file__), 'themes')]
html_theme = 'custom_theme'

# ...

In this example, we have added the custom theme HTML file to the Sphinx configuration file.

Example Use Case

To demonstrate the custom theme HTML file, we can create a simple example using the PSD class:

import numpy as np
from psd import PSD

# Create a PSD object
psd = PSD(method='welch', win_dur=10)

# Print the class attributes
print(psd.method)  # Output: welch
print(psd.win_dur)  # Output: 10

# Print the class methods
print(psd.__init__)  # Output: <function PSD.__init__ at 0x...>
print(psd.calculate)  # Output: <function PSD.calculate at 0x...>
print(psd.plot)  # Output: <function PSD.plot at 0x...>

Q: What is the issue with the current implementation of the `PSD` and `Spectrogram` classes?

A: The current implementation does not render the class docstrings online, making it challenging for users to access the instance attributes and methods of these classes.

Q: How can we customize the class docstring to include section headings for Attributes and Methods?

A: We can use the autoclass_content setting to render the class docstring and then use the autodoc_class_signature setting to render the methods. We can also add section headings for Attributes and Methods in the class docstring.

Q: How can we modify the theme HTML file to render the section headings correctly?

A: We can create a custom theme HTML file that overrides the default behavior. We can add custom section headings for Attributes and Methods and list the instance attributes and methods.

Q: What is the purpose of the `autoclass_content` setting?

A: The autoclass_content setting is used to render the class docstring. We can set it to 'class' to render the class docstring and then use the autodoc_class_signature setting to render the methods.

Q: What is the purpose of the `autodoc_class_signature` setting?

A: The autodoc_class_signature setting is used to render the class signature, which includes the section headings. We can set it to 'separated' to render the section headings correctly.

Q: How can we customize the Sphinx configuration file to apply the custom theme HTML file?

A: We can add the following lines to the conf.py file:

import os

# ...

# Custom theme HTML file
html_theme_path = [os.path.join(os.path.dirname(__file__), 'themes')]
html_theme = 'custom_theme'

# ...

Q: What is the purpose of the `html_theme_path` setting?

A: The html_theme_path setting is used to specify the path to the custom theme HTML file.

Q: What is the purpose of the `html_theme` setting?

A: The html_theme setting is used to specify the custom theme HTML file to be used.

Q: How can we create a simple example using the `PSD` class to demonstrate the custom theme HTML file?

A: We can create a simple example using the PSD class:

import numpy as np
from psd import PSD

# Create a PSD object
psd = PSD(method='welch', win_dur=10)

# Print the class attributes
print(psd.method)  # Output: welch
print(psd.win_dur)  # Output: 10

# Print the class methods
print(psd.__init__)  # Output: <function PSD.__init__ at 0x...>
print(psd.calculate)  # Output: <function PSD.calculate at 0x...>
print(psd.plot)  # Output: <function PSD.plot at 0x...>

In this example, we have created a PSD object and printed the class attributes and methods. The custom theme HTML file renders the section headings correctly, providing users with a clear understanding of the properties and methods of the PSD class.

Q: What are the benefits of using the custom theme HTML file?

A: The custom theme HTML file provides a clear and organized way to display the class attributes and methods, making it easier for users to understand the properties and methods of the PSD and Spectrogram classes.