Error making documentation when `SAGE_DOC_UNDERSCORE` is set.

[thecaligarmo]

Steps To Reproduce

When you set the SAGE_DOC_UNDERSCORE environmental variable, the documentation is supposed to build with all functions, including the hidden/private ones which start with _. We get many different types of errors:

1. Duplication error: This seems to be the biggest source of errors

OSError: /sage/sagedev/src/sage/manifolds/chart_func.py:docstring of sage.manifolds.chart_func.ChartFunction.__call__:1: WARNING: duplicate object description of sage.manifolds.chart_func.ChartFunction.__call__, other instance in sage/manifolds/chart_func, use :no-index: for one of them

As far as I can tell this is because .. automethod:: __call__ is set. We need some way to not create these duplicates. A weird thing of this one is that sometimes this error throws an OSError, but sometimes it doesn't. Not sure why.

2. Not a code object:

 OSError: WARNING: error while formatting arguments for sage.categories.category.Category._cmp_key: obj is not a code object

I'm not sure exactly why these ones happen, but in this example, it's because _cmp_key is not a method. It's being set as _cmp_key = _cmp_key which might be causing problems.

3. Inline substitution:

OSError: docstring of sage.coding.binary_code.BinaryCode._is_automorphism:5: WARNING: Inline substitution_reference start-string without end-string.

Not sure what this one is about, but I'm assuming there's an error in the docstring.

These are the 3 that my version picked up, but I'm sure there are more since I couldn't properly build the entire documentation.
This brings me to my next question: How do we want to handle private/hidden methods? A lot of them have documentation (examples, etc.) but don't have automethod added so they are hidden. But opening up all hidden/private methods might not be the way to go. In addition, there's no documentation that mentions that SAGE_DOC_UNDERSCORE is even an option.

As far as I can think, the following are some options we might want to consider, but I'm not sure what the best way forward is.

1. In regards to SAGE_DOC_UNDERSCORE:
   A. Get rid of SAGE_DOC_UNDERSCORE and choose either 2B or 2C
   B. Keep SAGE_DOC_UNDERSCORE and add it to the documentation.
2. Hidden/Private methods:
   A. Don't have hidden/private methods in the documentation and choose either 3A, 3B or 3C
   B. Show hidden methods in the documentation, but not private
   C. Show hidden and private methods in the documentation
3. Deal with documentation for hidden methods
   A. Don't change anything and have people still use automethod for the methods they want to add to the documentation
   B. Have some sort of automated system where if a hidden method has documentation we show it.
   C. Make some new tag so that instead of putting automethod in the class (far removed from the documentation itself and hard to know what has/hasn't been added) we put this new tag in the method itself to add it to the documentation.
4. Other options
   A. A second "Developers Reference" which implements 2B and the normal reference we keep as 2A

Expected Behavior

The documentation building to run smoothly.

Actual Behavior

Documentation building is throwing a ton of errors

Additional Information

No response

Environment

- **OS**: WSL
- **Sage Version**: 10.5 beta 2

Checklist

• I have searched the existing issues for a bug report that matches the one I want to file, without success.
• I have read the documentation and troubleshoot guide

[fchapoton]

Your point number 3. is a typical error in the rst syntax: Here the use of |--> without wrapping by double backticks.

[thecaligarmo]

Yes, I'm assuming a lot of the errors are just "normal" documentation errors that happen, but normally don't show up because this option to show underscore methods isn't set when we run documentation tests.

[thecaligarmo]

I've started a branch to try and address this:
https://github.com/thecaligarmo/sage/tree/doc-underscore

I've fixed most of the errors, but I'm stuck on the following ones:

1. InterfaceShellTransformer -

 OSError: /sage/sagedev/src/sage/repl/interpreter.py:docstring of sage.repl.interpreter.InterfaceShellTransformer.__init__:4: WARNING: duplicate object description of sage.repl.interpreter.InterfaceShellTransformer.temporary_objects, other instance in sage/repl/interpreter, use :no-index: for one of them

I tried adding a :no-index to the attribute, but it didn't do anything. In addition, I tried changing attribute to autoattribute and that caused errors.

2. Category -

 OSError: WARNING: error while formatting arguments for sage.categories.category.Category._cmp_key: obj is not a code object

I don't see what the error for this is exactly. I thought it was because _cmp_key didn't have a doc before it, but that didn't help.

3. BooleanMonomialMonoid -

OSError: docstring of sage.rings.polynomial.pbori.pbori.BooleanMonomialMonoid._element_constructor_:31: WARNING: Inline interpreted text or phrase reference start-string without end-string.

I can't find the text/phrase that is causing this issue.

4. Branch -

OSError: /sage/sagedev/src/sage/combinat/finite_state_machine.py:docstring of sage.combinat.finite_state_machine.Branch:1: WARNING: duplicate object description of sage.combinat.finite_state_machine.Branch, other instance in sage/combinat/finite_state_machine, use :no-index: for one of them

I can't find where Branch is even constructed in the documentation for me to be able to :no-index: it. No idea where to even begin with this one.

I also noticed some deprecation warnings, but I'm not sure if I should go ahead and fix those or just leave as is for now. For now I'm just leaving them as it feels like they should be a different PR.

[fchapoton]

for 2, maybe it's because of the line in category.py

    ``self.parent_class``, and :obj:`~sage.misc.unknown.Unknown` 

for 3, it's the s just after the link in

Convert from other :class:BooleanPolynomialRings ::

[thecaligarmo]

For 2. That didn't solve it (I removed the line entirely and still get the error)

For 3. That solved it! Thanks. (There was some additional errors that then popped up and I fixed those too). A few of them were ambiguous SEEALSO statements which I think I fixed appropriately, but not 100% certain.