Using `nbdev`'s pipeline for generating API documentations

[BirkhoffG]

nbdev_mkdocs generates API documentation using docstrings. This diverges from core ideas of how nbdev generates the documentation (e.g., nbdev's best practice).

I think it would be great to support API documentation like nbdev in order to reach broader nbdev users.

I would suggest:

• Support nbdev's directives to generate documentation.
• Give options to use nbdev's sym_links

[harishmohanraj]

Hi @BirkhoffG,

Yes, we support generating API documentation using docstrings. Docstrings are helpful in code editors such as Pycharm, Visual Studio, and Jupyter Notebooks, which provide a one keystroke access to help for a function if it has a docstring. We offer this as an additional feature to nbdev's existing functionality.

You can still generate documentation in nbdev's API documentation style by manually adding the notebooks to the sidebar.yml file and setting custom_sidebar = True in your settings.ini. We do not restrict the users to using one method over the other. The users have the freedom to choose the documentation look and feel that suits their specific needs.

Please refer to this guide for customising the sidebar navigation: https://nbdev-mkdocs.airt.ai/0.3/guides/Customizing_The_Sidebar

Regarding supporting directives and using nbdev's sym_links, we are currently working on it, and it will be supported in our future releases.

[harishmohanraj]

I'd like to share some additional information about using nbdev's directives and sym_links in nbdev_mkdocs. The sym_links and directives are supported out of the box when you generate your documentation in nbdev's API documentation style. Additionally, these sym_links and directives are supported in notebooks for tutorials and how-to guides (notebooks that are not part of API documentation). This means you can use directives like #|hide to hide cell input and output, or link a symbol by surround it with backticks, just as you would in nbdev.

Furthermore, nbdev_mkdocs can automatically detect function annotations from docstrings and create links in the documentation. For example, if you have a function that returns a Class from your library, nbdev_mkdocs will identify it and generate a handy link in the documentation for effortless navigation.

If you have any more questions or need further assistance, feel free to reach out.