CODEWITHSUNDEEP
pythonclasspython-sphinx
RNA
RNA

Reputation: 153651

how to document class attributes and special functions with sphinx correctly

I defined a class as shown in github repo. The sphinx conf.py is located here. When I run make html (which runs sphinx-build -b html -d build/doctrees source build/html), the attributes section is shown as "Variables". And weirdly, the 2 attributes defined as properties are show at the end of the doc page. How can I correctly show them as attributes in the doc?

And there are weird exp1 lines (at the bottom of the screenshot). I don't have comparison functions (like __ge__) defined - how did they show up in my documentation? How can suprress them?

enter image description here enter image description here enter image description here

I am running sphinx 3.1.1 on python 3.8. All the code/doc/settings are also in that github repo, if they help.

Upvotes: 1

Views: 860

Answers (1)

CypherX
CypherX

Reputation: 7353

Try commenting out lines 17 - 67 in the conf.py. It looks like all the unwanted output in your sphinx-generated documentation comes from these lines.

For the sake of ease of reviewing, I am also pasting the lines I suggested you to comment out here.

# NOTE: parts of this file were taken from scipy's doc/source/conf.py. See
# scikit-bio/licenses/scipy.txt for scipy's license.

import glob
import sys
import os
import re
import datetime

# Force matplotlib to not use any Xwindows backend.
import matplotlib
matplotlib.use('Agg')

import sphinx
import sphinx.ext.autosummary as autosummary

class NewAuto(autosummary.Autosummary):  ## line-17
    def get_items(self, names):
        # Camel to snake case from http://stackoverflow.com/a/1176023/579416
        first_cap_re = re.compile('(.)([A-Z][a-z]+)')
        all_cap_re = re.compile('([a-z0-9])([A-Z])')
        def fix_item(display_name, sig, summary, real_name):
            class_names = {
                'Experiment': 'exp'
            }

            class_name = real_name.split('.')[-2]
            if class_name in class_names:
                nice_name = class_names[class_name]
            else:
                s1 = first_cap_re.sub(r'\1_\2', class_name)
                nice_name = all_cap_re.sub(r'\1_\2', s1).lower()
                if len(nice_name) > 10:
                    nice_name = ''.join([e[0] for e in nice_name.split('_')])
            def fmt(string):
                count = string.count('%s')
                return string % tuple([nice_name] * count)

            specials = {
                '__eq__': fmt('%s1 == %s2'),
                '__ne__': fmt('%s1 != %s2'),
                '__gt__': fmt('%s1 > %s2'),
                '__lt__': fmt('%s1 < %s2'),
                '__ge__': fmt('%s1 >= %s2'),
                '__le__': fmt('%s1 <= %s2'),
                '__getitem__': fmt('%s[k]'),
                '__setitem__': fmt('%s[k] = v'),
                '__iter__': fmt('iter(%s)'),
                '__contains__': fmt('x in %s'),
                '__bool__': fmt('bool(%s)'),
                '__str__': fmt('str(%s)'),
                '__repr__': fmt('repr(%s)'),
                '__reversed__': fmt('reversed(%s)'),
                '__len__': fmt('len(%s)'),
                '__copy__': fmt('copy.copy(%s)'),
                '__deepcopy__': fmt('copy.deepcopy(%s)'),
            }
            if display_name in specials:
                return specials[display_name], '', summary, real_name
            return display_name, sig, summary, real_name

        skip = []

        return [fix_item(*e) for e in super(NewAuto, self).get_items(names)
                if e[0] not in skip]

autosummary.Autosummary = NewAuto  ## line-67

Upvotes: 1

Related Questions