We Keep Coding

Combining Sphinx Autodoc with Manual documentation

I am currently working on a reference documentation that was initially documented manually with .. class:: All classes in the modules where documented this way.
However, it was necessary recently to allow some automation to the documentation, such as show-inheritance of each class, but the problem now is how to combine the current manual documentation with autodoc.
I have tried to just simply replace .. class:: with .. autoclass:: but this resulted in a output where the description and parameters descriptions that were manually typed into the documentation (as against being generated from docstrings) to not be rendered in the output. Can anyone advise on what to do to solve this?
So here is more details:
Take a look at this:
.. autoclass:: wagtail.blocks.CharBlock
:show-inheritance:
.. class:: CharBlock
A single-line text input. The following keyword arguments are accepted in addition to the standard ones:
:param required: If true (the default), the field cannot be left blank.
:param max_length: The maximum allowed length of the field.
:param min_length: The minimum allowed length of the field.
:param help_text: Help text to display alongside the field.
:param validators: A list of validation functions for the field (see `Django Validators <https://docs.djangoproject.com/en/stable/ref/validators/>`__).
:param form_classname: A value to add to the form field's ``class`` attribute when rendered on the page editing form.
The output:
enter image description here
The issue is I have to repeat the class name, which would be rather confusing for the user of the documentation. autoclass would not render the parameters, hence the need for class. I need autoclass to be able to show the inheritance of the class(Bases). So I don't know if there is a directive that can perform the functions of class without me having to mention the class name, or is there any way I can force class not to take in any arguments?
I hope this clearer. Thanks

It is possible to use autodoc for some things (in this case it's just :show-inheritance:) and "manual" documentation (content that does not come from a docstring) for others, within the same directive.
Remove .. class:: and ensure that all lines after the .. autoclass:: line have the same indentation. I think this should produce the output that you want.
.. autoclass:: wagtail.blocks.CharBlock
:show-inheritance:
A single-line text input. The following keyword arguments are accepted in addition to the standard ones:
:param required: If true (the default), the field cannot be left blank.
:param max_length: The maximum allowed length of the field.
:param min_length: The minimum allowed length of the field.
:param help_text: Help text to display alongside the field.
:param validators: A list of validation functions for the field (see `Django Validators <https://docs.djangoproject.com/en/stable/ref/validators/>`__).
:param form_classname: A value to add to the form field's ``class`` attribute when rendered on the page editing form.

Unresolved reference in Django's docstring in PyCharm

I use Google Style Python Docstrings like in this Example for my Django's project.
When i create a class and using an attributes notation in docstring, Pycharm always say - "Unresolved reference".
class Post(models.Model):
"""
Class for posts.
Attributes:
title(str): Post title.
"""
title = models.CharField(max_length=120)
I understand that PyCharm doesn't see self for title and def __init__() function and write this error, but in Django I've never seen using def __init__() for classes inherited from models.
What should I do? Is this my error or does PyCharm not see context in this case? Should I use def __init__() or something else or write docsting in another way?

PyCharm does not appear to have support for this currently. The active issue for this in JetBrains issue tracker is https://youtrack.jetbrains.com/issue/PY-16760, please consider upvoting it to get it fixed. The only workaround if you want to avoid seeing these "Unresolved reference" errors in your docstrings is to disable the inspection in Preferences > Editor > Inspections > Unresolved references.
Another option that I have tried in the past is removing the "Attributes:" header and writing my attribute documentation on the same indentation level as the rest of the docstring. This no longer gives you a warning, but you are no longer conforming 100% to the Google Docstring Style Guide.

I solved this issue by adding a '# noqa' after the 'Attributes:', because i did not want to disable the unresolved reference warning.
So this would be the final docstring:
"""
Class for posts.
Attributes: # noqa
title(str): Post title.
"""

The following works for me: In your docstrings, writing Attribute: instead of Attributes: makes the error disappear. That allows you to keep the indentation level

classes or objects within a class/object

I read related posts but they didn't satisfy me.
Using tkinter i coded a class Musicsheet. Then I wrote classes of notes like wholeNote & halfNote, etc. After instantiaing MusicSheet followed by an instance of WholeNote, it looked ok, with the whole note on the music sheet. However, when I instantiated a half note the whole note had disappeared with just the half note on the sheet;it looks like halfNote had also instantiated ( sub classed?) a new music sheet thus previous notes/objects aren't there. This result in that the latest instance is always the only one on the sheet.
Thanks for the replies. Here are additional info:
class Musicsheet(Frame):
.......TCanvas initialization..
class WholeNote(MusicSheet):
......
class HalfNote(MusicSheet):
def __init__(self,x1,y1,x2,y2)
self.can.create_oval(x1,y1,x2,y2)
.....
more notes classes follow

Based on your current code:
Your note classes are derived from MusicSheet. I suppose you want the notes to be part of the sheet, not an instance of the Sheet. If you derive them from MusicSheet, the init of a Note would create a new instance of MusicSheet, not be added to the MusicSheet.
For Notes i recommend using Tkinter.CanvasItem class for inheritance.
(Type should be polygon for everything that is not a half/full rest or full note)
Using self.can.create_oval should be done in MusicSheet, not in Note Classes, as self.can should refer to the MusicSheet.

What is the standard Sphinx documentation format for a method?

I am trying to document my method using a standard format, but in my search I found many "standard" ways of documenting methods. My method is:
#staticmethod
def validateMasterAttribute(attribute):
...
and according to this official Python documentation I should document it like this:
#staticmethod
def validateMasterAttribute(attribute):
""" Validate that the entered master attribute has all the required nodes
Keyword arguments:
attribute -- type lxml.etree._Element, it is the xml node for the master attribute
Return:
Nothing if the node contains all the required sub nodes. Otherwise, it throws a TagNotFoundException exception
"""
...
however, it is written in this question that I should document it like:
#staticmethod
def validateMasterAttribute(attribute):
"""
Validate that the entered master attribute has all the required nodes
:attribute: type lxml.etree._Element, it is the xml node for the master attribute
return: Nothing if the node contains all the required sub nodes. Otherwise, it throws a TagNotFoundException exception
"""
...
I also found another docstring format, which seems old. What is the format that Sphinx can parse and generate web pages from?

You might want to consult Documenting Your Project Using Sphinx.
Alternatively you can use Napoleon which is an extension supporting google syntax for doctrings.
Choose one. Be consistent.

Colander subclassing SchemaNode

I wonder if someone can help me. I'm explore deform and colander in a new project and was following the documentation about subclassing SchemaNode. However, whilst the documentation states that
subclass can define the following methods and attributes: preparer,
validator, default, missing, name, title, description, widget, and
after_bind.
when I define title, it doesn't seem to come through. Here is some example code that I'm using:
class LocationSchemaNode(colander.SchemaNode):
schema_type = colander.Int
title = 'Location'
missing = None
validator = colander.Range(
min=1,
min_err='Please select a valid location'
)
class PersonSchema(colander.Schema):
location_id = LocationSchemaNode()
However, when the form is rendered the label for the field is "Location Id" not "Location" as per the title defined in SchemaNode. If instead I write:
class PersonSchema(colander.Schema):
location_id = LocationSchemaNode(title="Location")
Then all appears as I want, but the documentation seems to state I don't need to do this, and if I do it kind of defeats the point of pre-defining a SchemaNode if I have to keep defining fields.
Am I missing something, or is deform doing something that it shouldn't be (I doubt that is going to be the case). Any help is much appreciated.
Keith

This appears to be a bug that was fixed: https://github.com/Pylons/colander/pull/183
Also, the patch seems to be in the latest available release of colander so an update to the latest version should fix this issue.
Correction:
The example given in that PR exactly matches this question, but the fix given didn't actually fix that exact issue! So, I filed another PR to fix that issue and used the example given in #183 as the test. You can manually patch your own copy if you can't wait for the fix to be introduced into the repo or the next release.