dependencies for mkdocs + bug building the doc

[ReHoss]

Hi,

Several problems I found regarding the documentation:

• mkdocs is not in the requirements/project dependencies

• the build need a bunch of extra plugins that should be specified to the user

• when running mkdocs build an error occurs with the following output:

INFO    -  DeprecationWarning: Jupyter is migrating its paths to use standard platformdirs
given by the platformdirs library.  To remove this warning and
see the appropriate new directories, set the environment variable
`JUPYTER_PLATFORM_DIRS=1` and then run `jupyter --paths`.
The use of platformdirs will be the default in `jupyter_core` v6
  File "/home/hosseinkhan/Documents/work/phd/git_repositories/control_dde/venv/venv_control_dde/lib/python3.10/site-packages/jupyter_core/utils/__init__.py", line 90, in deprecation
    warnings.warn(message, DeprecationWarning, stacklevel=stacklevel + 1)
  File "/home/hosseinkhan/Documents/work/phd/git_repositories/control_dde/venv/venv_control_dde/lib/python3.10/site-packages/jupyter_client/connect.py", line 22, in 
    from jupyter_core.paths import jupyter_data_dir, jupyter_runtime_dir, secure_write

INFO    -  DeprecationWarning: 5.x style template file passed '/home/hosseinkhan/Documents/work/phd/git_repositories/control_dde/venv/venv_control_dde/lib/python3.10/site-packages/mknotebooks/templates/custom_markdown.tpl'. Use --template-name for the template directory with a index.<ext>.j2 file and/or --template-file to denote a different template.
  File "/home/hosseinkhan/Documents/work/phd/git_repositories/control_dde/venv/venv_control_dde/lib/python3.10/site-packages/traitlets/traitlets.py", line 1568, in _notify_observers
    c(event)
  File "/home/hosseinkhan/Documents/work/phd/git_repositories/control_dde/venv/venv_control_dde/lib/python3.10/site-packages/nbconvert/exporters/templateexporter.py", line 240, in _template_file_changed
    warnings.warn(

INFO    -  DeprecationWarning: Passing unrecognized arguments to super(HTMLExporter).__init__(template_path=['/home/hosseinkhan/Documents/work/phd/git_repositories/control_dde/venv/venv_control_dde/lib/python3.10/site-packages/mknotebooks/templates', '/home/hosseinkhan/Documents/work/phd/git_repositories/control_dde/venv/venv_control_dde/share/jupyter/nbconvert/templates/base', '/home/hosseinkhan/.local/share/jupyter/nbconvert/templates/base', '/usr/local/share/jupyter/nbconvert/templates/base', '/usr/share/jupyter/nbconvert/templates/base']).
object.__init__() takes exactly one argument (the instance to initialize)
This is deprecated in traitlets 4.2.This error will be raised in a future release of traitlets.
  File "/home/hosseinkhan/Documents/work/phd/git_repositories/control_dde/venv/venv_control_dde/lib/python3.10/site-packages/traitlets/traitlets.py", line 1385, in __init__
    warn(
  File "/home/hosseinkhan/Documents/work/phd/git_repositories/control_dde/venv/venv_control_dde/lib/python3.10/site-packages/traitlets/utils/warnings.py", line 14, in warn
    warnings.warn(msg, category=category, stacklevel=stacklevel, source=source)

INFO    -  Cleaning site directory
INFO    -  Building documentation to directory: /home/hosseinkhan/Documents/work/phd/git_repositories/torchdde/site
INFO    -  The following pages exist in the docs directory, but are not included in the "nav" configuration:
  - _static/README.md
ERROR   -  mkdocstrings: torchdde.integrate.integrate could not be found
ERROR   -  Error reading page 'usage/integration-de.md':
ERROR   -  Could not collect 'torchdde.integrate.integrate'

Aborted with a BuildError!

[thibmonsel]

Did you follow the Contribution.md to build the docs ?

[ReHoss]

Indeed, I did not. I thus will give it another try, and the dependencies are effectively present in docs/requirements.txt.

However, the documentation part of README.md should redirect to the Contribution part.

[thibmonsel]

closing issue with latest README update

[ReHoss]

@thibmonsel, I still have the same error when following the contribution part.

[ReHoss]

First, the docs/requirements.txt must be updated with the following package

pip install mkdocs-with-pdf

Second, I have a different but similar error on a fresh venv with torchdde installed with pip install .:

ImportError: Importing 'torchdde.TorchLinearInterpolator' failed, possible causes are:
            - an exception happened while importing
            - an element in the path does not exist
ERROR    -  Error reading page 'interpolators/linear-interpolator.md':
ERROR    -  Could not collect 'torchdde.TorchLinearInterpolator'

Aborted with a BuildError!

[thibmonsel]

I think, I know what is going on I make my latest changes in the branch neurips_submission and not master. Ill remove the pip install mkdocs-with-pdf too !

If you pull the new master it should be ok

[ReHoss]

pulling does not solve the issue.

[thibmonsel]

Could you give me the full error log

[ReHoss]

INFO     -  Building documentation...
INFO     -  Cleaning site directory
ERROR    -  mkdocstrings.extension: Importing 'torchdde.TorchLinearInterpolator' failed, possible causes are:
- an exception happened while importing
- an element in the path does not exist
Traceback (most recent call last):
  File "/home/hosseinkhan/Documents/work/phd/git_repositories/torchdde/venv/venv_torchdde/lib/python3.10/site-packages/pytkdocs/loader.py", line 264, in get_object_tree
    parent_module = importlib.import_module(parent_module_path)
  File "/usr/lib/python3.10/importlib/__init__.py", line 126, in import_module
    return _bootstrap._gcd_import(name[level:], package, level)
  File "<frozen importlib._bootstrap>", line 1050, in _gcd_import
  File "<frozen importlib._bootstrap>", line 1027, in _find_and_load
  File "<frozen importlib._bootstrap>", line 1006, in _find_and_load_unlocked
  File "<frozen importlib._bootstrap>", line 688, in _load_unlocked
  File "<frozen importlib._bootstrap_external>", line 883, in exec_module
  File "<frozen importlib._bootstrap>", line 241, in _call_with_frames_removed
  File "/home/hosseinkhan/Documents/work/phd/git_repositories/torchdde/torchdde/__init__.py", line 1, in <module>
    from .global_interpolation import TorchLinearInterpolator as TorchLinearInterpolator
  File "/home/hosseinkhan/Documents/work/phd/git_repositories/torchdde/torchdde/global_interpolation/__init__.py", line 1, in <module>
    from .linear_interpolation import TorchLinearInterpolator as TorchLinearInterpolator
  File "/home/hosseinkhan/Documents/work/phd/git_repositories/torchdde/torchdde/global_interpolation/linear_interpolation.py", line 4, in <module>
    import torch
ModuleNotFoundError: No module named 'torch'

The above exception was the direct cause of the following exception:

Traceback (most recent call last):
  File "/home/hosseinkhan/Documents/work/phd/git_repositories/torchdde/venv/venv_torchdde/lib/python3.10/site-packages/pytkdocs/cli.py", line 205, in main
    output = json.dumps(process_json(line))
  File "/home/hosseinkhan/Documents/work/phd/git_repositories/torchdde/venv/venv_torchdde/lib/python3.10/site-packages/pytkdocs/cli.py", line 114, in process_json
    return process_config(json.loads(json_input))
  File "/home/hosseinkhan/Documents/work/phd/git_repositories/torchdde/venv/venv_torchdde/lib/python3.10/site-packages/pytkdocs_tweaks/__init__.py", line 220, in process_config
    datas = _process_config(config)
  File "/home/hosseinkhan/Documents/work/phd/git_repositories/torchdde/venv/venv_torchdde/lib/python3.10/site-packages/pytkdocs/cli.py", line 91, in process_config
    obj = loader.get_object_documentation(path, members)
  File "/home/hosseinkhan/Documents/work/phd/git_repositories/torchdde/venv/venv_torchdde/lib/python3.10/site-packages/pytkdocs/loader.py", line 355, in get_object_documentation
    leaf = get_object_tree(dotted_path, self.new_path_syntax)
  File "/home/hosseinkhan/Documents/work/phd/git_repositories/torchdde/venv/venv_torchdde/lib/python3.10/site-packages/pytkdocs/loader.py", line 267, in get_object_tree
    raise ImportError(
ImportError: Importing 'torchdde.TorchLinearInterpolator' failed, possible causes are:
- an exception happened while importing
- an element in the path does not exist

ERROR    -  Error reading page 'interpolators/linear-interpolator.md':
ERROR    -  Could not collect 'torchdde.TorchLinearInterpolator'

Aborted with a BuildError!

EDIT: it works now after installing torch, please add it in docs/requirements.txt

[thibmonsel]

there is already torch in the pyproject.toml. Closing this issue.

[ReHoss]

None of the packages in install_requires are installed when running pip install ., except torchdde/* since it is specified by the hatch include directive.

You should replace the install_requires keyword with dependencies in the pyproject.toml file as recommended in the official documentation https://setuptools.pypa.io/en/latest/userguide/dependency_management.html#declaring-required-dependency such that the end user gets a working installation.

pip --version pip 22.0.2

[thibmonsel]

fixed it, by changing the keywork, thanks ! Check out latest commit3f44a57