Issue with case sensitivity on MacOS X

[astrofrog]

Astropy has M_bol and m_bol objects in the same sub-package, and this causes issues when using sphinx-automodapi because MacOS X is case-insensitive meaning that the .rst pages for each of these objects will conflict:

/Users/tom/Dropbox/Code/Astropy/astropy/docs/index.rst:: WARNING: toctree contains reference to nonexisting document 'api/astropy.units.function.logarithmic.m_bol'
/Users/tom/Dropbox/Code/Astropy/astropy/docs/index.rst:: WARNING: toctree contains reference to nonexisting document 'api/astropy.units.function.logarithmic.m_bol'
/Users/tom/Dropbox/Code/Astropy/astropy/docs/units/index.rst:389:<autosummary>:1: WARNING: py:obj reference target not found: astropy.units.function.logarithmic.m_bol
/Users/tom/Dropbox/Code/Astropy/astropy/docs/units/index.rst:: WARNING: toctree contains reference to nonexisting document 'api/astropy.units.function.logarithmic.m_bol'
/Users/tom/Dropbox/Code/Astropy/astropy/docs/units/index.rst:389:<autosummary>:: WARNING: toctree contains reference to nonexisting document 'api/astropy.units.function.logarithmic.m_bol'
/Users/tom/Dropbox/Code/Astropy/astropy/docs/units/logarithmic_units.rst:244:<autosummary>:1: WARNING: py:obj reference target not found: astropy.units.function.logarithmic.m_bol
/Users/tom/Dropbox/Code/Astropy/astropy/docs/units/logarithmic_units.rst:244:<autosummary>:: WARNING: toctree contains reference to nonexisting document 'api/astropy.units.function.logarithmic.m_bol'

[tonigi]

Hit this too. Perhaps there could be an option which causes file names to be rewritten (say, appending an underscore after each capital letter)?

[pllim]

Apple should just make their stuff be case sensitive. I don't see how we can fix this.

[bsipocz]

@pllim - I think we could maybe add a warning on osx, if there was any such sphinx warnings that say that some of the above might have been caused due to case sensitivity. As I recall it was a bit of a puzzle when we first run into the problem, such a warning would save a bit of time for anyone freshly running into it.

[bsipocz]

This has bitten me again, now with pyvo where we have classes like pyvo.auth.authsession.AuthSession. This generates warnings like these (via autodoc):

WARNING: autodoc: failed to import method 'AuthSession.add_security_method_for_url' from module 'pyvo.auth'; the following exception was raised:
Traceback (most recent call last):
  File "/Users/bsipocz/.pyenv/versions/3.11.0/lib/python3.11/site-packages/sphinx/util/inspect.py", line 440, in safe_getattr
    return getattr(obj, name, *defargs)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
AttributeError: module 'pyvo.auth.AuthSession' has no attribute 'add_security_method_for_url'

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

Traceback (most recent call last):
  File "/Users/bsipocz/.pyenv/versions/3.11.0/lib/python3.11/site-packages/sphinx/ext/autodoc/importer.py", line 102, in import_object
    obj = attrgetter(obj, mangled_name)
          ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/Users/bsipocz/.pyenv/versions/3.11.0/lib/python3.11/site-packages/sphinx/ext/autodoc/__init__.py", line 327, in get_attr
    return autodoc_attrgetter(self.env.app, obj, name, *defargs)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/Users/bsipocz/.pyenv/versions/3.11.0/lib/python3.11/site-packages/sphinx/ext/autodoc/__init__.py", line 2827, in autodoc_attrgetter
    return safe_getattr(obj, name, *defargs)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/Users/bsipocz/.pyenv/versions/3.11.0/lib/python3.11/site-packages/sphinx/util/inspect.py", line 456, in safe_getattr
    raise AttributeError(name) from exc
AttributeError: add_security_method_for_url

/Users/bsipocz/munka/devel/pyvo/docs/api/pyvo.auth.AuthSession.rst:19:<autosummary>:1: WARNING: py:obj reference target not found: pyvo.auth.AuthSession.AuthSession.add_security_method_for_url
/Users/bsipocz/munka/devel/pyvo/docs/api/pyvo.auth.AuthSession.rst:19:<autosummary>:1: WARNING: py:obj reference target not found: pyvo.auth.AuthSession.AuthSession.delete
/Users/bsipocz/munka/devel/pyvo/docs/api/pyvo.auth.AuthSession.rst:19:<autosummary>:1: WARNING: py:obj reference target not found: pyvo.auth.AuthSession.AuthSession.get
/Users/bsipocz/munka/devel/pyvo/docs/api/pyvo.auth.AuthSession.rst:19:<autosummary>:1: WARNING: py:obj reference target not found: pyvo.auth.AuthSession.AuthSession.post
/Users/bsipocz/munka/devel/pyvo/docs/api/pyvo.auth.AuthSession.rst:19:<autosummary>:1: WARNING: py:obj reference target not found: pyvo.auth.AuthSession.AuthSession.put
/Users/bsipocz/munka/devel/pyvo/docs/api/pyvo.auth.AuthSession.rst:19:<autosummary>:1: WARNING: py:obj reference target not found: pyvo.auth.AuthSession.AuthSession.update_from_capabilities

and an rst file like this:

AuthSession
===========

.. currentmodule:: pyvo.auth

.. autoclass:: AuthSession
   :show-inheritance:

   .. rubric:: Methods Summary

   .. autosummary::

      ~AuthSession.add_security_method_for_url
      ~AuthSession.delete
      ~AuthSession.get
      ~AuthSession.post
      ~AuthSession.put
      ~AuthSession.update_from_capabilities

   .. rubric:: Methods Documentation

   .. automethod:: add_security_method_for_url
   .. automethod:: delete
   .. automethod:: get
   .. automethod:: post
   .. automethod:: put
   .. automethod:: update_from_capabilities

[bsipocz]

Note, this case is someone different from the m_bol vs M_bol, as there is only one AuthSession class, and it's exposed in the auth.AuthSession namespace, there is no need for having anything for the authsession.py module...

[bsipocz]

OK, same stuff different phrasing: https://github.com/sphinx-doc/sphinx/issues/1495

[bsipocz]

And here is a patch that maybe useful for us, too?: https://github.com/scikit-learn/scikit-learn/pull/13022

[HealthyPear]

Hello!

I think I got the same issue as @bsipocz where I am using macos with sphinx-automodapi v0.14.1 and sphinx 5.3.0.

In my package I have a module pyswgo.io.eventsource which contains the class EventSource with a (static) method called is_compatible and when I compile the docs I get for example

WARNING: autodoc: failed to import method 'EventSource.is_compatible' from module 'pyswgo.io'; the following exception was raised:
Traceback (most recent call last):
  File "/Users/michele/Applications/mambaforge/envs/pyswgo/lib/python3.9/site-packages/sphinx/util/inspect.py", line 376, in safe_getattr
    return getattr(obj, name, *defargs)
AttributeError: module 'pyswgo.io.EventSource' has no attribute 'is_compatible'

/Users/michele/Applications/SWGO/irf-production/docs/api/pyswgo.io.EventSource.rst:30:<autosummary>:1: WARNING: py:obj reference target not found: pyswgo.io.EventSource.EventSource.is_compatible

Is this the same issue?

I know of the existence of the autosummary_filename_map and I naïvely tested it as

autosummary_filename_map = {"pyswgo.io.eventsource.Eventsource": "EventSource"}

right after the extensions dictionary in conf.py, but to no use.

Is there any news about this issue?

If for some reason my problem is of a different nature I will gladly bother your with a new issue :)

[bsipocz]

I tried a bit of autosummary_filename_map but it didn't work out of the box for the pyvo case above, and I haven't dug deep enough yet to see what needed to be fixed for automodapi to allow it to work. To be practical, ultimately I may just go ahead and rename or merge the files that have the same names as the single class they contain.