Error and exception when running on a fresh and (almost) empty repository.

[jenstroeger]

Describe the bug

I tried using the package on this Python Package Template repo (to replace the existing Markdown builder) and generating docs fails in two ways:

• if no docs/_build/markdown/index.md file pre-exists then I get a warning (run)

  [Errno 2] No such file or directory: '/home/runner/work/python-package-template/python-package-template/docs/_build/markdown/index.md'

• if there’s not much content (like is the case for that repo) then this assertion fires (run)

   Exception occurred:
   File "/opt/hostedtoolcache/Python/3.10.12/x64/lib/python3.10/site-packages/sphinx_markdown_builder/contexts.py", line 256, in make
     assert len(content) > 0, "Empty table"
  AssertionError: Empty table

To Reproduce

Check out the repository on branch try-sphinx-markdown-builder for PR https://github.com/jenstroeger/python-package-template/pull/585, and then

make venv
. .venv/bin/activate
make setup
make docs  # This will fail.

The last command will fail with the above errors.

Expected behavior

That last command should build the markdown docs.

Enviroment (please complete the following information):

• OS: macOS
• Version: 13.4

Additional context

n/a

[liran-funaro]

@jenstroeger First of all, thank you for taking the time to report the issue you encountered. Your contribution is truly appreciated!

I'm pleased to inform you that I've addressed the bug and released a new version (v0.6.4) on PyPI. Kindly update to the latest release and let me know if it resolves the problem on your end.

If the issue is now resolved, I would be grateful if you could close the GitHub issue. Your feedback helps maintain and improve the package for everyone.

Once again, thank you for your valuable input!

[jenstroeger]

Thanks @liran-funaro for the swift fix, and thank you for picking up this Sphinx Markdown package — I look forward to seeing it evolve into generating better Markdown 🤓

I updated to the latest release and all tests pass now: https://github.com/jenstroeger/python-package-template/pull/585

One slightly misleading message, however, is

writing output... 
WARNING: error accessing file /path/to/python-package-template/docs/_build/markdown/index.md: [Errno 2] No such file or directory: '/path/to/python-package-template/docs/_build/markdown/index.md'

but I’m not sure if this comes from Sphinx or from the Markdown extension.

---

For context: in the Package Template I use that Markdown plugin to automatically generate the Wiki for that repo (link) and there are a few things where the Markdown could be improved — are you interested in feedback?

[liran-funaro]

One slightly misleading message [...]

It is indeed misleading. It was a mistake in my code. I fixed it in the latest commit. Since it is a low severity, I'll postpone the release until higher severity changes are applied.

[...] there are a few things where the Markdown could be improved — are you interested in feedback?

I'm very interested in feedback. Please feel free to open issues/PRs.

My tests are lacking, so any contribution will be highly appreciated. I believe that suggesting changes to the tests as a PR better reflects your contribution to this project.

Please check out the tests folders: tests/source and tests/expected. You are encouraged to suggest improvements or additions to these tests to capture relevant use cases.

[liran-funaro]

@jenstroeger

I've added an issue template for a discrepancy report.

The discrepancy report allows for quick reporting of issues with the generated output. For example, missing line breaks, wrong format, etc.

If you have time and wish your contribution to be better reflected in the project, consider opening a PR that improves, fixes, or adds tests. This is instead or in addition to opening an issue. For more information, see Contributing Tests.

[jenstroeger]

Thank @liran-funaro for the fix above and for all the additional information, will do!

For now, let me close this PR as completed 👍🏼