portray

portray copied to clipboard

@timothycrosley Thanks for creating this very useful package.

Is there any way of letting portray know to look for modules in the src directory? The project in question is generic_validation.

With the default configuration I get the following error:

(generic_validation) ~/PythonProjects/generic_validation$ portray in_browser
Done Copying source documentation to temporary compilation directory
Module not found: generic_validation

Below is the content of the project setup.py file:

import setuptools

with open("README.md", "r", encoding="utf-8") as fh:
    long_description = fh.read()

setuptools.setup(
    name="generic_validation",
    version="0.0.6",
    author="D Reschner",
    author_email="[email protected]",
    description="Generic validation decorators.",
    long_description=long_description,
    long_description_content_type="text/markdown",
    url="https://github.com/simphotonics/generic_validation",
    project_urls={
        "Bug Tracker": "https://github.com/simphotonics/generic_validation/issues",
    },
    classifiers=[
        "Programming Language :: Python :: 3",
        "License :: OSI Approved :: BSD 3-Clause License",
        "Operating System :: OS Independent",
    ],
    package_dir={"": "src"},
    packages=setuptools.find_packages(where="src"),
    python_requires=">=3.6",
)

---

To make it work I had to manually modify the entry directory by editing the pyproject.toml file:

[tool.portray]
repo_url = "https://github.com/simphotonics/generic_validation"
extra_markdown_extensions = ["fenced_code", "pymdownx.superfences"]
directory = "/home/dan/PythonProjects/generic_validation/src"    # <========= Added this option.

and copy README.md to src so that it gets picked up.

My current project configuration is listed below:

(generic_validation) ~/PythonProjects/generic_validation$: portray project_configuration
{'append_directory_to_python_path': True,
'directory': '/home/dan/PythonProjects/generic_validation/src',        <============== appended /src
'docs_dir': 'docs',
'extra_dirs': ['art', 'images', 'media'],
'extra_markdown_extensions': ['fenced_code', 'pymdownx.superfences'],
'file': '/home/dan/PythonProjects/generic_validation/pyproject.toml',
'host': '127.0.0.1',
'include_reference_documentation': True,
'labels': {'Api': 'API', 'Cli': 'CLI', 'Http': 'HTTP', 'Pypi': 'PyPI'},
'mkdocs': {'config_file_path': '/home/dan/PythonProjects/generic_validation',
           'edit_uri': 'edit/main/',
           'markdown_extensions': ['admonition',
                                   'codehilite',
                                   'extra',
                                   'pymdownx.details',
                                   'pymdownx.highlight',
                                   'fenced_code',
                                   'pymdownx.superfences'],
           'repo_name': 'generic_validation',
           'repo_url': 'https://github.com/simphotonics/generic_validation',
           'site_name': 'generic_validation',
           'theme': {'custom_dir': '/home/dan/.virtualenvs/generic_validation/lib/python3.8/site-packages/portray/mkdocs_templates',
                     'name': 'material',
                     'palette': [{'accent': 'lightgreen',
                                  'primary': 'teal',
                                  'scheme': 'default',
                                  'toggle': {'icon': 'material/toggle-switch-off-outline',
                                             'name': 'Switch to dark mode'}},
                                 {'accent': 'lightgreen',
                                  'primary': 'teal',
                                  'scheme': 'slate',
                                  'toggle': {'icon': 'material/toggle-switch',
                                             'name': 'Switch to light '
                                                     'mode'}}]}},
'modules': ['generic_validation'],
'output_dir': 'site',
'pdocs': {'exclude_source': False,
          'modules': ['generic_validation'],
          'overwrite': True},
'port': 8000,
'repo_url': 'https://github.com/simphotonics/generic_validation'}

---

The other thing I tried was to use:

(generic_validation) ~/PythonProjects/generic_validation$ portray in_browser -m src

The command above starts the server and generates documentation but lists src as the top module and generic_validation as a submodule.

Any fixes? I added the same option you did and now I'm not getting the error, but I still have my project as a submodule, and the page is empty with no documentation

@ZaneEme. Did you activate your virtual environment? You have to install portray and run e.g. portray in_browser from within the virtual environment. See quick-start.

To make sure you have the same configuration you could try to clone the package mentioned above and build the documentation.

Would also be happy to have a simple solution to use this with src layout!