timothycrosley / portray

Your Project with Great Documentation.
MIT License
861 stars 74 forks source link

tool.portray.mkdocs.theme.custom_dir Error #65

Closed KyleKing closed 3 years ago

KyleKing commented 3 years ago

I ran into some issues configuring the as_html output to work locally (navigation and search of the HTML documentation without mkdocs serve). The error also happens when using in_browser

Working MKDocs setup

poetry add mkdocs-localsearch

In mkdocs.yml

use_directory_urls: false

theme
  name: material
  custom_dir: docs/_theme

plugins:
  - search
  - localsearch

In docs/_theme/main.html

{% extends "base.html" %}
{% block config %}
{% if "localsearch" in config["plugins"] %}
<script src="https://unpkg.com/iframe-worker/polyfill"></script>
<script src="{{ 'search/search_index.js' | url }}"></script>
{% endif %}
{% endblock %}

Portray Configuration

To pyproject.toml

[tool.portray.mkdocs]
use_directory_urls = false
plugins = [ "search", "localsearch" ]

[tool.portray.mkdocs.theme]
name = "material"
palette = {primary = "blue grey", accent = "pink"}
custom_dir = "docs/_theme"

If I comment out the last line (custom_dir = "docs/_theme"), the rest of the configuration seems to work fine

Error

Python 3.8.3 and portray Version: 1.4.0

When running poetry run portray as_html (or in_browser), I get this error:

❯ poetry run portray as_html
Done Copying source documentation to temporary compilation directory
Done Auto generating reference documentation using pdocs
Traceback (most recent call last):
  File "/Users/kyleking/Developer/recipes/.venv/bin/portray", line 8, in <module>
    sys.exit(__hug__.cli())
  File "/Users/kyleking/Developer/recipes/.venv/lib/python3.8/site-packages/hug/api.py", line 441, in __call__
    result = self.commands.get(command)()
  File "/Users/kyleking/Developer/recipes/.venv/lib/python3.8/site-packages/hug/interface.py", line 650, in __call__
    raise exception
  File "/Users/kyleking/Developer/recipes/.venv/lib/python3.8/site-packages/hug/interface.py", line 646, in __call__
    result = self.output(self.interface(**pass_to_function), context)
  File "/Users/kyleking/Developer/recipes/.venv/lib/python3.8/site-packages/hug/interface.py", line 129, in __call__
    return __hug_internal_self._function(*args, **kwargs)
  File "/Users/kyleking/Developer/recipes/.venv/lib/python3.8/site-packages/portray/api.py", line 37, in as_html
    render.documentation(
  File "/Users/kyleking/Developer/recipes/.venv/lib/python3.8/site-packages/portray/render.py", line 50, in documentation
    with documentation_in_temp_folder(config) as documentation_output:  # type: str
  File "/usr/local/Caskroom/miniconda/base/lib/python3.8/contextlib.py", line 113, in __enter__
    return next(self.gen)
  File "/Users/kyleking/Developer/recipes/.venv/lib/python3.8/site-packages/portray/render.py", line 155, in documentation_in_temp_folder
    mkdocs(config["mkdocs"])
  File "/Users/kyleking/Developer/recipes/.venv/lib/python3.8/site-packages/portray/render.py", line 69, in mkdocs
    config_instance = _mkdocs_config(config)
  File "/Users/kyleking/Developer/recipes/.venv/lib/python3.8/site-packages/portray/render.py", line 164, in _mkdocs_config
    errors, warnings = config_instance.validate()
  File "/Users/kyleking/Developer/recipes/.venv/lib/python3.8/site-packages/mkdocs/config/base.py", line 115, in validate
    post_failed, post_warnings = self._post_validate()
  File "/Users/kyleking/Developer/recipes/.venv/lib/python3.8/site-packages/mkdocs/config/base.py", line 95, in _post_validate
    config_option.post_validation(self, key_name=key)
  File "/Users/kyleking/Developer/recipes/.venv/lib/python3.8/site-packages/mkdocs/config/config_options.py", line 462, in post_validation
    config_dir = os.path.dirname(config.config_file_path)
  File "/usr/local/Caskroom/miniconda/base/lib/python3.8/posixpath.py", line 152, in dirname
    p = os.fspath(p)
TypeError: expected str, bytes or os.PathLike object, not NoneType

Summary

What configuration information is portray missing?

KyleKing commented 3 years ago

The problem was that the custom_dir was not an absolute path and it works when set to custom_dir = "/Users/kyleking/Developer/recipes/docs/_theme"

Follow up questions:

Update: submitted a PR to resolve the absolute path. The config item as_html --local is likely too specific to this one use case and would potentially create edge cases where merging configuration options would be challenging