Blob Blame History Raw
# Sphinx-generated HTML documentation is not suitable for packaging; see
# https://bugzilla.redhat.com/show_bug.cgi?id=2006555 for discussion.
#
# We can generate PDF documentation as a substitute.
%bcond_without doc_pdf
 
Name:           python-autoclasstoc
Version:        1.3.0
Release:        %autorelease
Summary:        Add a succinct TOC to auto-documented classes

License:        MIT
URL:            https://github.com/kalekundert/autoclasstoc
Source0:        %{pypi_source autoclasstoc}

# Remove useless shebang lines
# https://github.com/kalekundert/autoclasstoc/pull/17
Patch0:         %{url}/pull/17.patch

BuildArch:      noarch

BuildRequires:  python3-devel

%if %{with doc_pdf}
BuildRequires:  make
BuildRequires:  python3-sphinx-latex
BuildRequires:  latexmk
%endif

%global common_description %{expand:
It’s surprisingly difficult to document large Python classes in a way that’s
easy for users to navigate. Most projects use the autodoc Sphinx plugin, which
simply puts the complete documentation for each class member one after another.
While this does fully document the class, it doesn’t give the user a quick way
to see everything the class can do. This makes classes of even moderate
complexity difficult to navigate. It also encourages projects to be stingy
about which class members to include in the documentation (e.g. excluding
special methods, inherited methods, private methods, and/or undocumented
methods), to the further detriment of the user.

What’s needed is for each class to have a succinct table of contents (TOC)
that:

  • Is organized into sections that will be meaningful to the user. Different
    projects and classes may call for different sections, e.g. public/private
    methods, methods that share a decorator, methods with a common prefix, etc.
  • Includes every method of the class (so that the documentation is complete),
    while still making it easy for the user to get a sense for what the class
    does and find what they’re looking for.
  • Collapses inherited methods. Complex classes in particular can inherit a
    lot of methods from their parent classes, and while these methods should be
    present in the TOC (since they’re part of the class), collapsing them makes
    it easier for the user to grok the functionality provided by the class
    itself.

autoclasstoc provides a new Restructured Text directive that is all of these
things. It also works well with autodoc and autogen, and should be easy to
incorporate into any existing project.

See the complete documentation (https://autoclasstoc.readthedocs.io/en/latest)
for more information (including examples).}

%description %{common_description}


%package -n python3-autoclasstoc
Summary:        %{summary}

%description -n python3-autoclasstoc %{common_description}


%package doc
Summary:        Documentation for autoclasstoc

%description doc %{common_description}


%prep
%autosetup -n autoclasstoc-%{version} -p1

# Patch out coverage dependencies
sed -r -i '/\b(pytest-cov|coveralls)\b/d' pyproject.toml

# Drop intersphinx mappings, since we can’t download remote inventories and
# can’t easily produce working hyperlinks from inventories in local
# documentation packages.
echo 'intersphinx_mapping.clear()' >> docs/conf.py


%generate_buildrequires
%pyproject_buildrequires -x tests%{?with_doc_pdf:,docs}


%build
%pyproject_wheel

%if %{with doc_pdf}
PYTHONPATH="${PWD}" %make_build -C docs latex SPHINXOPTS='%{?_smp_mflags}'
%make_build -C docs/_build/latex LATEXMKOPTS='-quiet'
%endif


%install
%pyproject_install
%pyproject_save_files autoclasstoc


%check
%pytest


%files -n python3-autoclasstoc -f %{pyproject_files}
%license LICENSE.txt
%doc README.rst


%files doc
%license LICENSE.txt
%doc CHANGELOG.md
%doc README.rst
%if %{with doc_pdf}
%doc docs/_build/latex/autoclasstoc.pdf
%endif


%changelog
%autochangelog