tdkorn / sphinx-readme

Generate Beautiful reStructuredText README.rst for GitHub, PyPi, GitLab, BitBucket

Hey! I'm Adam 👋

I'm a biologist turned computer scientist excited by the potential of biotechnology and neurotechnology to transform the world.

My goal is to help drive innovation and contribute to the advancement of these industries, but I'm open-minded and willing to try almost anything.

I also really like cats.

🔎 Where to Reach Me

 Email

 LinkedIn

 Instagram

sphinx-readme's Issues

Needs Unit Testing

This extension seriously needs some unit testing done but I'm not exactly sure how to approach this. Hoping for some help please!

Error on self toctree

I was getting this error:

Traceback (most recent call last):
  File "/Users/jimboy/Documents/CS/send-the-raven/.venv/lib/python3.10/site-packages/sphinx/events.py", line 96, in emit
    results.append(listener.handler(self.app, *args))
  File "/Users/jimboy/Documents/CS/send-the-raven/.venv/lib/python3.10/site-packages/sphinx_readme/__init__.py", line 51, in resolve
    parser.resolve()
  File "/Users/jimboy/Documents/CS/send-the-raven/.venv/lib/python3.10/site-packages/sphinx_readme/parser.py", line 289, in resolve
    rst = self.replace_toctrees(src, rst)
  File "/Users/jimboy/Documents/CS/send-the-raven/.venv/lib/python3.10/site-packages/sphinx_readme/parser.py", line 383, in replace_toctrees
    link, subs = format_hyperlink(target, text=entry['title'])
  File "/Users/jimboy/Documents/CS/send-the-raven/.venv/lib/python3.10/site-packages/sphinx_readme/utils/rst.py", line 36, in format_hyperlink
    if "`" in text:
TypeError: argument of type 'NoneType' is not iterable

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

Traceback (most recent call last):
  File "/Users/jimboy/Documents/CS/send-the-raven/.venv/lib/python3.10/site-packages/sphinx/application.py", line 355, in build
    self.events.emit('build-finished', None)
  File "/Users/jimboy/Documents/CS/send-the-raven/.venv/lib/python3.10/site-packages/sphinx/events.py", line 107, in emit
    raise ExtensionError(__("Handler %r for event %r threw an exception") %
sphinx.errors.ExtensionError: Handler <function resolve at 0x1062e0550> for event 'build-finished' threw an exception (exception: argument of type 'NoneType' is not iterable)

During handling of the above exception, another exception occurred:

Traceback (most recent call last):
  File "/Users/jimboy/Documents/CS/send-the-raven/.venv/lib/python3.10/site-packages/sphinx/events.py", line 96, in emit
    results.append(listener.handler(self.app, *args))
  File "/Users/jimboy/Documents/CS/send-the-raven/.venv/lib/python3.10/site-packages/sphinx_readme/__init__.py", line 51, in resolve
    parser.resolve()
  File "/Users/jimboy/Documents/CS/send-the-raven/.venv/lib/python3.10/site-packages/sphinx_readme/parser.py", line 289, in resolve
    rst = self.replace_toctrees(src, rst)
  File "/Users/jimboy/Documents/CS/send-the-raven/.venv/lib/python3.10/site-packages/sphinx_readme/parser.py", line 383, in replace_toctrees
    link, subs = format_hyperlink(target, text=entry['title'])
  File "/Users/jimboy/Documents/CS/send-the-raven/.venv/lib/python3.10/site-packages/sphinx_readme/utils/rst.py", line 36, in format_hyperlink
    if "`" in text:
TypeError: argument of type 'NoneType' is not iterable

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

Traceback (most recent call last):
  File "/Users/jimboy/Documents/CS/send-the-raven/.venv/lib/python3.10/site-packages/sphinx/cmd/build.py", line 285, in build_main
    app.build(args.force_all, args.filenames)
  File "/Users/jimboy/Documents/CS/send-the-raven/.venv/lib/python3.10/site-packages/sphinx/application.py", line 361, in build
    self.events.emit('build-finished', err)
  File "/Users/jimboy/Documents/CS/send-the-raven/.venv/lib/python3.10/site-packages/sphinx/events.py", line 107, in emit
    raise ExtensionError(__("Handler %r for event %r threw an exception") %
sphinx.errors.ExtensionError: Handler <function resolve at 0x1062e0550> for event 'build-finished' threw an exception (exception: argument of type 'NoneType' is not iterable)

When I am trying to put my index.rst on toctree using self:

Documentation
============

.. toctree::
   :maxdepth: 2
   :hidden:
   
   Get Started <self>
   example
   api
   contribute

Support for explicit titles in toctrees

Toctree titles currently only come from document titles:

sphinx-readme/sphinx_readme/parser.py

Lines 259 to 263 in 01ad647

	for _, entry in toctree.get('entries', []):
	toc['entries'].append({
	'entry': entry,
	'title': self.titles.get(entry),
	})

A toctree with explicit titles such as

.. toctree::
   :caption: Documentation

   API Documentation <modules>

Should use API Documentation as the entry title, not the title of modules.rst

Add support for more than one level of TocTree

Toctrees are currently parsed as if they have the :titlesonly: option but they obviously should be parsed up to :maxdepth: depth

Add support for ```:external:``` role and all intersphinx syntax

Need to add support for :external: role

:external:domain:role:`target`
:external:role:`target`
:external+invname:domain:role:`target`
:external+invname:role:`target`

Also for the syntax below. It doesn't seem to be documented? But I found it on StackOverflow so...

:role:`invname:target`
:domain:role:`invname:target`

Plus all of the above with explicit titles 😭 for example

:external:domain:role:`title <target>`

Nested admonitions become unnested when replaced with ```list-table```

It's better than not rendering but it still isn't ideal

Continuation of #1

Replacing admonitions with csv-table directives doesn't work for admonitions with code blocks or nested admonitions

csv-table directives are used to replace admonitions when the raw directive can't be used.

There is no way to put

• A csv-table inside of a csv-table
• A code-block inside of a csv-table

The list-table directive does allow for this though, so it should be used instead

Multiline rubrics aren't replaced properly

Add support for `std` and `py` domain cross-references with the `:domain:role:` syntax

Cross references like :py:class:`READMEParser` and :std:confval:`readme_src_files` aren't replaced properly

If an intersphinx cross-reference is only present within a "readme" ```only``` directive, it won't be parsed

For example, if this cross-reference:

.. only:: readme

   The :mod:`sphinx.ext.linkcode` extension is no longer needed for this package

isn't present anywhere other than this directive block, the cross-reference won't be parsed by sphinx because the only directive will be removed. So currently, the reference won't be resolved.

When generating a new doctree via get_doctree(), the intersphinx cross-references are present but the nodes end up being nodes.problematic instead of nodes.reference

Currently thinking to just go through the intersphinx inventory to determine the target but I'm not sure if that's the optimal approach

Error if repo_dir and package name don't agree

Hi, as I'm checking out your package, I run into a bug.

It is on Line 52 of utils/linkcode.py:

https://github.com/TDKorn/sphinx-readme/blob/0a5fe5d7ed6af950beaeb4b32febcccffdad4171/sphinx_readme/utils/linkcode.py#L52C5-L52C5

    repo_dir = get_repo_dir()
    pkg = pkg_resources.require(repo_dir.name)[0]

My project's dir name and Python package aren't the same. Hence, using the repo_dir to search for the package failed with the pkg_resources.DistributionNotFound exception.

It has been a while since I last wrote a Sphinx extension, but I think there is a way to get the Python package name from Extension API. Basically, accessing the information Sphinx's autodoc uses.

update (12/12): Spent a bit of time deep-diving the code, and what it appears to need is a conf.py variable (something like readme_repo_package) and present its value to pkg_resources.require() if given, else use the current auto-detected package name. What do you think?