I am using nbdev to write a software package and encountered the following issue, which is possibly associated with the nbdev_export command: When I run nbdev_preview to check the rendered html version of my source code for documentation, the documentation for show_doc has automatically been added three times to the very end of the rendered html page with my source code, even though the built-in nbdev show_doc function has not been imported or used in the jupyter notebook with my source code (which is named 01_code.ipynb, following the nbdev documentation). I can see the markdown for show_doc (3 times!) in the markdown file in _proc/_docs/core.html.md located in my project’s root directory, but I am reluctant to manually edit this file (and the associated _proc/_docs/core.html file) as it is automatically generated, to my understanding, when running nbdev_export. Does anybody of you have any suggestions how to prevent that the documentation for nbdev’s show_doc function is automatically added to the documentation/markdown of my own source code? Or how to properly remove it after my source code has been exported? My tests all run successfully (with nbdev_test) and I am pretty sure I don’t mix any import statements with actual code, which is known to cause issues with nbdev. Running nbdev_clean has no effect on this issue, and re-running nbdev_export doesn’t fix it either.
You’re encountering a somewhat common issue with nbdev where the documentation for show_doc gets duplicated in the output. Here are a few suggestions to help resolve this:
Check for Accidental Imports: Ensure that there’s no accidental import or usage of show_doc in any cells of your Jupyter notebook. Sometimes a stray import or a comment can trigger it.
Reset the Notebook: Sometimes, restarting the kernel and re-running all cells can help. This ensures that any cached state in the notebook doesn’t interfere with the output. Receiptify Music
Inspect Other Notebooks: If you have multiple notebooks in your nbdev project, check if show_doc is referenced in those. It can sometimes aggregate documentation from multiple files.
Check Markdown Cells: Review the markdown cells in your notebook to ensure none are referencing show_doc inadvertently.
Customizing show_doc Behavior: If you’re using custom functions or altering show_doc, ensure you’re not inadvertently duplicating the documentation.
Manual Edit: As a last resort, if you still encounter the issue after trying the above suggestions, you can manually edit the _proc/_docs/core.html.md file to remove the duplicates. While this is not ideal, it can serve as a temporary workaround until you pinpoint the root cause.
Updating nbdev: Make sure you’re using the latest version of nbdev. Sometimes, bugs are fixed in newer releases.
Thank you for your feedback and detailed suggestions!
I’ve carefully gone through each point but none of them was the root cause in my case. I also confirmed this by running the following bash command from the root of my project repo: grep -rni --include="*.ipynb" --include="*.md" "show_doc" nbs/ produces no output. However, the following command showed several lines in files within the _procdirectory, including the redundant show_doc documentation: grep -rni --include="*.ipynb" --include="*.md" "show_doc" _proc
In the meantime, I’ve been able to identify the root cause. In brief, in my source code, I have defined a decorator function, named add_to_cass, that allows adding methods to an existing Assistant class dynamically. For each method where this add_to_class decorator is being used to extend the Assistant class, the show_doc documentation is being added to my source code documentation page.
I have opened issue #1446, which can be found here, in case anybody else is experiencing a similar issue.