[docs] add naming convention defaults for nose and pytest

[mickeypash]

Introducing a small table with a legend detailing the default naming conventions used by nose and pytest
Based on the following discussion.

Adding the tables here:

Convention	unittest	pytest
Ⓜ test*.py	✅
Ⓜ test_*.py	✅	✅
Ⓜ *_test.py		✅
Ⓜ *_tests.py
Ⓒ *(unittest.TestCase)	✅	✅
ⓜ test_*	✅	✅
Ⓒ Test*		✅
ⓜ test_*		✅
ⓕ test_*		✅

Legend
Ⓜ	module
Ⓒ	Class
ⓜ	method
ⓕ	function

[RonnyPfannschmidt]

https://pytest--8502.org.readthedocs.build/en/8502/how-to/nose.html?highlight=nose#unsupported-idioms-known-issues <- looks like the legend is missing

[nicoddemus]

We also should rebase this after #8505 gets merged. 👍

[nicoddemus]

Also not sure if it is only for me, but the symbols look really blurry:

[mickeypash]

Thanks @RonnyPfannschmidt
I wasn't aware of this docs preview! I'll try to familiarise myself with the doc build process to avoid these issues.

• Fix legend

@nicoddemus

• Wait for Fix plugin-list label in the docs #8505 to get merged
• Rebase from main

The symbols look fine for me. I'm using the Brave Browser on MacOS

[nicoddemus]

The symbols look fine for me. I'm using the Brave Browser on MacOS

Thanks for the double check!

That screenshot was from Chrome on Windows.

This is from Firefox on Windows:

So we can disregard that, must be something with my Chrome/system. 👍

[nicoddemus]

We still have build failures:

/home/runner/work/pytest/pytest/doc/en/how-to/nose.rst:82: WARNING: Unknown target name: "test".
/home/runner/work/pytest/pytest/doc/en/how-to/nose.rst:84: WARNING: Unknown target name: "test".
/home/runner/work/pytest/pytest/doc/en/how-to/nose.rst:85: WARNING: Unknown target name: "test".

Seems like the Ⓜ test_*.py lines are being as target directives... 🤔

[bluetech]

Nice!

[bluetech]

Perhaps I'm missing something but isn't this the same as two lines above?

[mickeypash]

Well spotted! 🙇
I looked at the source material as at this point it's a bit of a blur.
I'll need to fix the indentation somehow!
I think the original slide demonstrates it better:

[mickeypash]

I'm not too familiar with RST syntax, found this in the documentation Escaping Mechanism but I don't think it would serve me here. If you have any suggestions that would be great!

[mickeypash]

That explains a lot!😅 I tried a number of combinations of \ to escape them but to no avail. I'll try again later.

[andrewdotn]

This will work with non-breaking spaces:

..
   The nbsp trick is from https://stackoverflow.com/a/12145490/14558

.. |nbsp| unicode:: 0xA0
   :trim:

=============================================== ======== ======
Convention                                      nose     pytest
=============================================== ======== ======
Ⓜ test*.py                                       ✅
Ⓜ test_*.py                                      ✅       ✅
Ⓜ \*_test.py                                              ✅
Ⓜ \*_tests.py
|nbsp| |nbsp| Ⓒ \*\(unittest.TestCase\)           ✅       ✅
|nbsp| |nbsp| |nbsp| |nbsp| ⓜ test\_\*            ✅       ✅
|nbsp| |nbsp| Ⓒ Test\*                                     ✅
|nbsp| |nbsp| |nbsp| |nbsp| ⓜ test\_\*                     ✅
|nbsp| |nbsp| ⓕ test\_\*                                   ✅
=============================================== ======== ======

And that’ll even work through LaTeX too.

[Zac-HD]

I pushed a small change, using an extra column so we can drop the symbols and legend, and using code formatting to fix some .rst issues where the patterns were interepreted as markup:

I'm sorry it's taken literal years to merge such a nice little PR - thanks for opening it, and for all your patience 😅