Package: dunderlab-docs
DunderLab's Documentation GuideThis Python module facilitates the creation ofSphinx Documentationdirectly fromJupyter Notebooks. Essentially, it provides a preconfigured environment that utilizesnbsphinxin the background, complete with custom styles and preloaded modules.Installation$pipinstall-Udunderlab-docsTo generateSphinx documentation, start with thesphinx-quickstartcommand. Then, in the Sphinxconf.pyfile, add 'sphinx' anddunderlab.docsto the extensions list.extensions=['nbsphinx','dunderlab.docs',]Configurationdunderlab_custom_indexThis setting allows you to insert a custom ReStructuredText into theindex.rstfile. This custom index will be rendered following the main index and will also appear in the sidebar.dunderlab_custom_index=f""".. toctree:::glob::maxdepth: 2:name: mastertoc3:caption: Submodule 1notebooks/submodule1/*.. toctree:::glob::maxdepth: 2:name: mastertoc3:caption: Submodule 2notebooks/submodule2/*"""dunderlab_color_linksCustomize your documentation's appearance by altering the link colors. For instance, settingdunderlab_color_linksto#4db6acchanges all links to a blue shade, adding a unique touch to your documentation. Remember, changes to the stylesheet impact the entire documentation, so test thoroughly before publishing.dunderlab_color_links='#4db6ac'dunderlab_code_referenceThis configuration value can be used to disable the generation of certain index inputs in Sphinx documentation. Specifically, setting toTruewill enable the generation of the index inputs genindex, modindex, and search, while setting it toFalsewill disable their generation.dunderlab_code_reference=Falsedunderlab_github_repositoryThis configuration specifies the project repository, which will be used to adjust the URLs of the images in theREADME.mdfile.NotebooksIn the first build, for examplemake clean html, the system will create (if not yet exist) the foldernotebookswith some files in it.docs/
    build/
    source/
        conf.py
        index.rst
        _modules/
        _static/
        _templates/
->      notebooks/
->          01-getting_started.ipynb
->          readme.ipynb
->          __sandbox.ipynbThereadme.ipynbnotebook is mandatory, as it generates theREADME.mdfile in the root of the Python package. Documentation notebooks should be named with numeric prefixes for sorting purposes. Notebooks named with__prefixes won't be rendered into the documentation.Special Notebooks namesreadme.ipynbThis notebook is used to generate the main documentation page, which is typically theindex.rst file. The notebook is converted into a ReStructuredText file, which is then rendered as HTML to create the main documentation page. Additionally, thereadme.ipynbnotebook is also used to generate theREADME.mdfile that is typically found in the root of your project. This file can provide a brief overview of your project and its purpose, along with any relevant installation or usage instructions.license.ipynbThis notebook is used to generate theLICENSEfile that is typically found in the root of your project. This file specifies the terms under which your code is licensed and provides information about how others can use and modify your code. It is recommended that thelicense.ipynbnotebook contain a single Markdown or plain text cell that includes the full text of your project's license. This can help ensure that the license text is accurate and up-to-date, and can simplify the process of updating the license if needed.footer.ipynbThis notebook is used to generate a footer that appears at the bottom of the main documentation page and the project'sREADME.mdfile. It can contain any content you want to include in the footer, such as copyright information, acknowledgments, or links to related resources. During the documentation build process, the notebook is converted into HTML and added to the bottom of the main documentation page andREADME.mdfile.FeaturesAutomatic generation of README.mdAutomatic index in html viewCompatibe withRead the DocsTroubleshootingIf the Index and Module Index appear empty:Resolve this by adding the target module's path to the PATH variable in theconf.pyfileimportosimportsyssys.path.insert(0,os.path.abspath('relative_path_to_module'))If images aren't visible in the readmereadme.md file:Verify their paths to ensure they're accessible from the GitHub repository. Relative paths must be correctly set relative to theREADME.mdfile's location.The images used in thereadme.ipynbnotebook should be placed in a folder called_images.