Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Preview does not appear to update toctree #705

Open
alcarney opened this issue Dec 29, 2023 · 1 comment
Open

Preview does not appear to update toctree #705

alcarney opened this issue Dec 29, 2023 · 1 comment
Labels
bug Something isn't working lsp Issues that relate to the language server
Milestone

Comments

@alcarney
Copy link
Member

I'm not entirely sure why, but for themes like furo where the documentation's toctree is rendered as a sidebar, the sidebar is not updated when documents are added to/removed from the toctree.

@alcarney alcarney added bug Something isn't working lsp Issues that relate to the language server labels Dec 29, 2023
@alcarney alcarney added this to the 1.0 milestone Dec 29, 2023
@alcarney alcarney added this to Esbonio Dec 29, 2023
@github-project-automation github-project-automation bot moved this to Todo in Esbonio Dec 29, 2023
@alcarney
Copy link
Member Author

Unsurprisingly, the way esbonio is running Sphinx breaks a few assumptions.
For this situation in particular there are some caches that are causing Sphinx to process stale toctree data leading to the sidebars not reacting to changes being made.

The first is that on the BuildEnvironment class the top-level doctree is cached

@functools.cached_property
def master_toctree(self) -> nodes.document:
    return self.get_doctree(self.config.root_doc)

and since this field is pickled, the stale data can even persist across restarts of the Sphinx process.
It should however, be simple enough to override this in the sphinx agent to be a regular @property.

The other cache is in the get_doctree() method

def get_doctree(self, docname: str) -> nodes.document:
    """Read the doctree for a file from the pickle and return it."""
    try:
        serialised = self._pickled_doctree_cache[docname]
    except KeyError:
        filename = path.join(self.doctreedir, docname + '.doctree')
        with open(filename, 'rb') as f:
            serialised = self._pickled_doctree_cache[docname] = f.read()

    doctree = pickle.loads(serialised)
    doctree.settings.env = self
    doctree.reporter = LoggingReporter(self.doc2path(docname))
    return doctree

by editing this method to not use a cache at all I can confirm this fixes the stale toctree issue, however I'm sure for larger projects this will greatly hurt performance of incremental updates.

So I expect a more elegant solution will be for the sphinx agent to clear the relevant fields from the cache when it knows a document has been updated.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
bug Something isn't working lsp Issues that relate to the language server
Projects
Status: Todo
Development

No branches or pull requests

1 participant