Support LaTeX build

[haiiliin]

Description

autoclasstoc seems to only work on html build, this pull request tries to support the LaTeX build.

For example, with the following simple usage:

.. autoclass:: pandas.DataFrame
   :members:

   .. autoclasstoc::

An exception occurs:

Exception occurred:
  File "C:\Users\Hailin\AppData\Local\Programs\Python\Python310\lib\site-packages\sphinx\util\nodes.py", line 636, in _new_copy
    newnode = self.__class__(self.rawsource, **self.attributes)
TypeError: details.__init__() got an unexpected keyword argument 'ids'

This is because the signature of the constructor of the details node is not compatible with the Element node: https://github.com/kalekundert/autoclasstoc/blob/1e209b22ffd958fbdff394c9db2d7aadeddd0ea1/autoclasstoc/nodes.py#L9-L19 Whereas the signature of Element's constructor is:

def __init__(self, rawsource='', *children, **attributes):

Thus the signature of the details's constructor is updated to be compatible with Element:

def __init__(self, rawsource='', *children, open_by_default=False, **attributes):

The argument open_by_default is now key-value-only argument.

To further configure the LaTeX builder for the nodes and details_summary nodes, we have to define a custom LaTeX translator:

class AutoClassTocLaTexTranslator(LaTeXTranslator):
    """A custom LaTeX translator that incorporates the `details` and `details_summary` nodes."""

    def visit_details(self, node):
        pass

    def depart_details(self, node):
        pass

    def visit_details_summary(self, node):
        pass

    def depart_details_summary(self, node):
        self.body.append('\n')

Because I don't find an environment in LaTeX to insert collapsible content, the details implementation is left blank. A new line should be inserted after every details_summary node in LaTeX so that they won't be in the same line.

[haiiliin]

@kalekundert I have no idea why this pull request breaks the tests.

[kalekundert]

Thanks for the PR! It'd definitely be good to support LaTeX builds. This might be beyond the scope of this PR, but it could be nice to add a config option that determines whether or not collapsible content is included in LaTeX documents (basically expand/collapse at build time).

Regarding the test failures, I've had issues using python 3.7 on ubuntu-latest with some of my other repositories. If that's the issue here, the solution would be to specify ubuntu-20.04 in .github/workflows/test.yml. That said, I've never seen this exact error before, so I could be totally wrong.

It'd also be good to include a LaTeX build in the tests, especially because it seems like exactly the kind of thing that'd be easy to break unintentionally.

[haiiliin]

Regarding the test failures, I've had issues using python 3.7 on ubuntu-latest with some of my other repositories. If that's the issue here, the solution would be to specify ubuntu-20.04 in .github/workflows/test.yml. That said, I've never seen this exact error before, so I could be totally wrong.

It seems that the tests still fail on ubuntu-20.04

[kalekundert]

I realized I misread the test logs last time: these just look like normal test failures. Do the tests also fail when you run them locally?

The 5 tests that are failing are all defined in test_autoclasstoc.py and test_autoclasstoc.nt. I'll try to give a little background info on these tests, in case it helps with debugging. First of all, these tests all work by (i) using sphinx to build a small project and then (ii) checking that the resulting HTML contains all the expected elements. The code for building the projects and making the comparisons is found in test_autoclasstoc.py. The parameters that vary between each text (namely the files to create in the project directory and the expected HTML elements to check for) are specified in test_autoclasstoc.nt.

Each test project is built in its own temporary directory. You can find the path to this directory in the pytest output. For example, here's the path for one of the failing tests on GitHub:

tmp_files = TestPath('/tmp/pytest-of-runner/pytest-2/test_autoclasstoc_link_data_at0')

This directory is very useful for debugging:

• It contains all the input files, so you can re-run sphinx directly for just that directory if you want to. I often find this easier than rerunning pytest, plus sometimes its helpful to modify the input files and see what happens.
• It contains all the output HTML files, so you can look at them in a web browser and see what's exactly wrong, e.g. is an element totally missing, is it just in the wrong place, etc.
• It contains files called stdout and stderr, which contain any output that was captured when sphinx was running.

[codecov-commenter]

Codecov Report

Merging #35 (d7f425c) into master (6d0f2bd) will decrease coverage by 1.26%. The diff coverage is 83.33%.

:mega: This organization is not using Codecov’s GitHub App Integration. We recommend you install it so Codecov can continue to function properly for your repositories. Learn more

@@            Coverage Diff             @@
##           master      #35      +/-   ##
==========================================
- Coverage   98.57%   97.31%   -1.26%     
==========================================
  Files           6        6              
  Lines         280      298      +18     
  Branches       38       40       +2     
==========================================
+ Hits          276      290      +14     
- Misses          1        3       +2     
- Partials        3        5       +2     

Impacted Files	Coverage Δ
autoclasstoc/utils.py	93.00% <60.00%> (-3.81%)	:arrow_down:
autoclasstoc/nodes.py	100.00% <100.00%> (ø)
autoclasstoc/plugin.py	97.61% <100.00%> (+0.11%)	:arrow_up:

Help us with your feedback. Take ten seconds to tell us how you rate us. Have a feature suggestion? Share it here.

[haiiliin]

I don't know why setting a LaTeX translator would break the HTML tests, but anyway, now the tests pass.