Sphinx: Autosection Label Extension does not work

[Daltz333]

I have the following project and branch

In this project I have the 'sphinx.ext.autosectionlabel' extension installed, see this.

I have a RST file called ip-networking and networking-basics. Whenever I try to reference ip-networking in networking-basics, I am given the following warning with no link generated.

C:\Users\Dalton Smith\Documents\frc-docs\source\docs\networking\networking-basics.rst:64: WARNING: undefined label: ip-networking (if the link has no caption the label must precede a section header)

I am referencing it using the following syntax

See the :ref:`IP Networking Article <ip-networking>` for more information.

I don't know if this is improper project configuration, or a bug. Thanks :)

I'll be happy to provide any additional information.

Development Environment:
OS: Windows 10 1903
Sphinx Version: 2.0.1
Python Version: 3.7.3

[tk0miya]

Please use sectioning title for reference (ex. :ref:`IP Networking`). It seems ip-networking and networking-basics are not title of your document.

If you want to create a link to the top of "document", please use :doc: role instead.
https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#role-doc

[Daltz333]

The docs stated that it prefixes the filename to the front. So would it not be ip-networking:sectiontitle? @tk0miya

[tk0miya]

By default, the prefix is not needed. It is only needed when you enables autosectionlabel_prefix_document option in your conf.py.

[Daltz333]

The option is indeed enabled. That is why I am confused on the syntax.

[tk0miya]

On my local, :ref:`ip-networking:IP Networking` works fine with this settings:

autosectionlabel_prefix_document = True

Could you check this please?

[Daltz333]

Ohh I see. You use the document file-name only when referencing a section specifically, otherwise its the title of the document. That was quite confusing and annoying to find out. Thanks.

[Daltz333]

@tk0miya Reopening this as the issue is yet to be solved. I'm still getting this error on my feature/autosection-label branch.

C:\Users\daltz\OneDrive\Documents\frc-docs\source\docs\networking\networking-basics.rst:63: WARNING: undefined label: ip-networking:ip networking (if the link has no caption the label must precede a section header)

With the following reference

See the :ref:`ip-networking:IP Networking` for more information.

Source at https://github.com/Daltz333/frc-docs/tree/feature/autosection-label

[tk0miya]

It seems ip-networking.rst is placed under networking directory. So it should be referenced as :ref:`networking/ip-networking:IP Networking`. autosectionlabel prepends docname relative from source directory to sectioning title.

[Daltz333]

Oh. Man that took way too long to figure out.

[poikilotherm]

I just came across the same issue and did not want to open a new issue.
@tk0miya would you like a pull request to the docs, including a clarified section about the exact behaviour?

[tk0miya]

@poikilotherm Yes, please. It's very helpful to me because I'm not native speaker.