Refactor the documentation for facade sets

[kwankyu]

We fix the somewhat weird location of the documentation of facade sets.

CC: @tscrim

Component: documentation

Branch/Commit: u/klee/26848 @ 611b8f0

Reviewer: Kwankyu Lee

Issue created by migration from https://trac.sagemath.org/ticket/26848

[kwankyu]

Branch: u/klee/26848

[sagetrac-git]

Branch pushed to git repo; I updated commit sha1. New commits:

a4dd555

Refactor the documentation of facade sets

[sagetrac-git]

Commit: a4dd555

[kwankyu]

Author: Kwankyu Lee

[jhpalmieri]

comment:5

The problem with facade sets is a symptom, not the actual problem. Compare the Python 2 and 3 builds of the reference manual for reference/categories/sage/categories/sets_cat.html, for example (which you get to by choosing "Categories" in the main reference manual index, and then "Sets"). With Python 2, the documentation for the class Sets includes various subclasses and methods (for example, an_element), while with Python 3 with your branch, all of that is missing: it only includes the top-level docstring. This is the reason that, without your branch, the reference to facade-sets is broken: that part of the documentation is omitted in the Python 3 build, so the reference (naturally) can't be found.

This is being discussed at #26522, and that's where we should focus attempts to fix this problem.

[kwankyu]

comment:6

Replying to @jhpalmieri:

The problem with facade sets is a symptom, not the actual problem. Compare the Python 2 and 3 builds of the reference manual for reference/categories/sage/categories/sets_cat.html, for example (which you get to by choosing "Categories" in the main reference manual index, and then "Sets"). With Python 2, the documentation for the class Sets includes various subclasses and methods (for example, an_element), while with Python 3 with your branch, all of that is missing: it only includes the top-level docstring. This is the reason that, without your branch, the reference to facade-sets is broken: that part of the documentation is omitted in the Python 3 build, so the reference (naturally) can't be found.

This is being discussed at #26522, and that's where we should focus attempts to fix this problem.

This ticket is independent from #26522. This just fixes a small problem toward building the complete sage documentation. With this ticket, at least make doc finishes successfully. This would facilitate solving other (big) problems like your #26522.

Moreover as far as I can see, a solution of #26522 would not fix what this ticket solves, contrary to your belief. It seems to me that the problem of #26522 is related with Sphinx autodoc extension specialized for Sage...

[jhpalmieri]

comment:7

Replying to @kwankyu:

This ticket is independent from #26522. This just fixes a small problem toward building the complete sage documentation. With this ticket, at least make doc finishes successfully.

It might finish without error, but I would not agree that it finishes successfully: the built documents are missing huge chunks.

This would facilitate solving other (big) problems like your #26522.

Moreover as far as I can see, a solution of #26522 would not fix what this ticket solves, contrary to your belief. It seems to me that the problem of #26522 is related with Sphinx autodoc extension specialized for Sage...

A solution to #26522 would mean that no parts of the documentation are omitted, so cross-references would resolve correctly. That would solve the problem in this ticket, as I explained above.

[kwankyu]

comment:8

This ticket is independent from #26522. This just fixes a small problem toward building the complete sage documentation. With this ticket, at least make doc finishes successfully.

It might finish without error,

I once again checked that it finishes without error with the patch.

but I would not agree that it finishes successfully: the built documents are missing huge chunks.

True.

Moreover as far as I can see, a solution of #26522 would not fix what this ticket solves, contrary to your belief.

I withdraw my assertion. #26522 would also make make doc work. But a merit of this ticket is to relocate the documentation for facade sets to a better place.

A solution to #26522 would mean that no parts of the documentation are omitted, so cross-references would resolve correctly.

I agree. But I still believe this ticket has its own merits, independent from #26522.

[embray]

comment:11

Ticket retargeted after milestone closed (if you don't believe this ticket is appropriate for the Sage 8.8 release please retarget manually)

[sagetrac-git]

Branch pushed to git repo; I updated commit sha1. New commits:

81ae781	Merge branch 'develop'
b9f73ee	Merge branch 'develop' into refactor-facade-sets-documentation-trac26848

[sagetrac-git]

Changed commit from a4dd555 to b9f73ee

[sagetrac-git]

Changed commit from b9f73ee to 6594005

[sagetrac-git]

Branch pushed to git repo; I updated commit sha1. This was a forced push. New commits:

6594005

Refactor the documentation of facade sets

[embray]

comment:14

Moving tickets from the Sage 8.8 milestone that have been actively worked on in the last six months to the next release milestone (optimistically).

[sagetrac-git]

Changed commit from 6594005 to 0d240ff

[sagetrac-git]

Branch pushed to git repo; I updated commit sha1. This was a forced push. New commits:

0d240ff

Refactor the documentation for facade sets

[embray]

comment:17

Ticket retargeted after milestone closed

[mkoeppe]

comment:18

Batch modifying tickets that will likely not be ready for 9.1, based on a review of the ticket title, branch/review status, and last modification date.

[tscrim]

comment:20

I am not sure I agree with moving this. Where it is, it is a natural entry point when using the command ? doc. So I would instead propose just having a link in the facade_sets.py category module level documentation.

[sagetrac-git]

Changed commit from 0d240ff to 611b8f0

[sagetrac-git]

Branch pushed to git repo; I updated commit sha1. This was a forced push. New commits:

611b8f0

Refactor the documentation of facade sets

[kwankyu]

comment:22

Replying to @tscrim:

I am not sure I agree with moving this. Where it is, it is a natural entry point when using the command ? doc. So I would instead propose just having a link in the facade_sets.py category module level documentation.

OK. Now I see your point.

[tscrim]

Changed author from Kwankyu Lee to none

[tscrim]

comment:23

Thank you for your efforts in trying to improve the documentation in Sage.

[tscrim]

Reviewer: Kwankyu Lee

[fchapoton]

comment:24

Is this really duplicate/invalid/wontfix ?

[kwankyu]

comment:25

Replying to @fchapoton:

Is this really duplicate/invalid/wontfix ?

Yes.