Recommended way to create own Docs for Dash apps?

[KMouratidis]

I am trying to create a documentation (more like reference for internal usage) for a Dash project (spanning many files, server.py holding the app and every other file loading the app from there). Is there a suggested way to do this?

---

I tried using pdoc3 but when trying to use it on any file containing a callback it seems be loading the same module multiple times thus triggering an error in Dash ("output with ID X alread exists"). I've opened an issue there (pdoc3 issue) hoping that I can at least get some pointers as to how to work around it, but I figured maybe someone here had a better suggestion to make.

[emmanuelle]

Hi @KMouratidis, what would you like to document about your app? How to use it, how to deploy it, some specific components, the API of your callbacks, or all of the above? For documenting the app, the dash docs are actually a collection of dash applications themselves, you can take a look at the source code in https://github.com/plotly/dash-docs/tree/master/tutorial. If you want to document an API or write some text-only (no user interaction) narrative documentation, have you tried sphinx?

[KMouratidis]

Thanks for the quick reply!

I mainly want the documentation to be able to export the docstrings (which inlcude basic type information, hints for usage, and short/long summaries). The functions and classes are both callbacks and generic/non-Dash, and some module docstrings since the whole project spans multiple directories. It is not meant to be usage docs, so I'd rather not make a separate app for that. Finally, I haven't tried sphinx although if there is no suggested way I probably will; it just seemed too complex to start there (hence pdoc).

[KMouratidis]

I did try sphinx and it does not work either; same issue.

Example traceback

.

WARNING: autodoc: failed to import module 'Networks' from module 'EDA_miner2.apps.exploration'; the following exception was raised:
Traceback (most recent call last):
  File "/home/kmourat/venv/lib/python3.6/site-packages/sphinx/ext/autodoc/importer.py", line 154, in import_module
    __import__(modname)
  File "/home/kmourat/Desktop/MWE2/EDA_miner2/apps/exploration/Networks.py", line 99, in <module>
    [State("user_id", "children")])
  File "/home/kmourat/venv/lib/python3.6/site-packages/dash/dash.py", line 1018, in callback
    self._validate_callback(output, inputs, state)
  File "/home/kmourat/venv/lib/python3.6/site-packages/dash/dash.py", line 836, in _validate_callback
    raise exceptions.DuplicateCallbackOutput(msg)
dash.exceptions.DuplicateCallbackOutput: 
                Multi output ..in_node.options...out_node.options.. contains an `Output` object
                that was already assigned.
                Duplicates:
                {'in_node.options', 'out_node.options'}
                

WARNING: autodoc: failed to import module 'PDF_report' from module 'EDA_miner2.apps.exploration'; the following exception was raised:
Traceback (most recent call last):
  File "/home/kmourat/venv/lib/python3.6/site-packages/sphinx/ext/autodoc/importer.py", line 154, in import_module
    __import__(modname)
  File "/home/kmourat/Desktop/MWE2/EDA_miner2/apps/exploration/PDF_report.py", line 162, in <module>
    State("row1_header_input", "value")])
  File "/home/kmourat/venv/lib/python3.6/site-packages/dash/dash.py", line 1018, in callback
    self._validate_callback(output, inputs, state)
  File "/home/kmourat/venv/lib/python3.6/site-packages/dash/dash.py", line 836, in _validate_callback
    raise exceptions.DuplicateCallbackOutput(msg)
dash.exceptions.DuplicateCallbackOutput: 
                Multi output ..graph12.figure...graph21.figure...row1col1.children...header_text.children...row1_header_text.children.. contains an `Output` object
                that was already assigned.
                Duplicates:
                {'graph12.figure',
 'graph21.figure',
 'header_text.children',
 'row1_header_text.children',
 'row1col1.children'}

It seems the only way to resolve this is by not using dash.Dash which does checks to validate whether no duplicate components exist. For now I'm using this snippet as an alternative to mimic the same behavior

class app:
    def callback(*argument):
        def decorator(function):
            def wrapper(*args, **kwargs):
                result = function(*args, **kwargs)
                return result
            return wrapper
        return decorator

Is there a way to avoid this similar to using suppress_callback_exceptions ?