Opened 5 years ago

Closed 5 years ago

#20255 closed enhancement (fixed)

deprecated_function_alias should not appear in the documentation of posets

Reported by: jmantysalo Owned by:
Priority: major Milestone: sage-7.2
Component: documentation Keywords:
Cc: Merged in:
Authors: Jeroen Demeyer Reviewers: Marc Mezzarobba
Report Upstream: N/A Work issues:
Branch: 09c288a (Commits) Commit: 09c288af4239b36b19e3a3504ced1fe4e5649db6
Dependencies: Stopgaps:

Change History (16)

comment:1 follow-up: Changed 5 years ago by jdemeyer

Can you more concretely give an example of something that changed, to understand better what this bug is about?

comment:2 in reply to: ↑ 1 Changed 5 years ago by jmantysalo

Replying to jdemeyer:

Can you more concretely give an example of something that changed, to understand better what this bug is about?

I installed Sage to our server just like version 7.0 before. And now see for example http://sage-doc.sis.uta.fi/reference/combinat/sage/combinat/posets/posets.html. It contains intervals() which is deprecated and also doctring for deprecated_function_alias().

comment:3 follow-up: Changed 5 years ago by jdemeyer

  • Description modified (diff)

I don't believe this has changed, I think it was always like this.

comment:4 in reply to: ↑ 3 ; follow-up: Changed 5 years ago by jmantysalo

  • Type changed from defect to enhancement

Replying to jdemeyer:

I don't believe this has changed, I think it was always like this.

I tested with 6.10. True, except that deprecated_function_alias() was not included is posets.html.

comment:5 Changed 5 years ago by jdemeyer

  • Description modified (diff)
  • Summary changed from Remove deprecated functions from generated html documentation to deprecated_function_alias should not appear in the documentation of posets

comment:6 Changed 5 years ago by jmantysalo

I think that also there should not be deprecated functions visible in documentation. Or at least we should have an option to hide them, just like we already have for TESTS-blocks.

comment:7 in reply to: ↑ 4 ; follow-up: Changed 5 years ago by jdemeyer

Replying to jmantysalo:

True, except that deprecated_function_alias() was not included is posets.html.

Then why not say that from the beginning if that is the real bug?

comment:8 Changed 5 years ago by jdemeyer

  • Authors set to Jeroen Demeyer

comment:9 in reply to: ↑ 7 Changed 5 years ago by jmantysalo

Replying to jdemeyer:

Replying to jmantysalo:

True, except that deprecated_function_alias() was not included is posets.html.

Then why not say that from the beginning if that is the real bug?

Because I remembered wrong. I think that before this deprecated functions were not listed on html doc.

comment:10 Changed 5 years ago by jdemeyer

  • Branch set to u/jdemeyer/deprecated_function_alias_should_not_appear_in_the_documentation_of_posets

comment:11 Changed 5 years ago by jdemeyer

  • Commit set to 09c288af4239b36b19e3a3504ced1fe4e5649db6
  • Status changed from new to needs_review

New commits:

09c288aDo not import deprecated_function_alias in classes

comment:12 follow-up: Changed 5 years ago by jmantysalo

Should examples at developers manual, section "Deprecation", also be changed? They kind of suggests wrong way to make a deprecation.

comment:13 in reply to: ↑ 12 ; follow-up: Changed 5 years ago by jdemeyer

Replying to jmantysalo:

They kind of suggests wrong way to make a deprecation.

The intent of the documentation is clear to me (you almost never want to import something inside a class), but I'm open to suggestions.

comment:14 in reply to: ↑ 13 Changed 5 years ago by jmantysalo

Replying to jdemeyer:

Replying to jmantysalo:

They kind of suggests wrong way to make a deprecation.

The intent of the documentation is clear to me (you almost never want to import something inside a class), but I'm open to suggestions.

I tried this:

diff --git a/src/doc/en/developer/coding_in_python.rst b/src/doc/en/developer/coding_in_python.rst
index 4eec8bd..2f237a7 100644
--- a/src/doc/en/developer/coding_in_python.rst
+++ b/src/doc/en/developer/coding_in_python.rst
@@ -491,19 +491,23 @@ documentation for more information on its behaviour and optional arguments.
   ``my_function(my_old_keyword=5)`` will see a warning::
 
       from sage.misc.decorators import rename_keyword
-      @rename_keyword(deprecation=666, my_old_keyword='my_new_keyword')
-      def my_function(my_new_keyword=True):
-          return my_new_keyword
+      ...
+
+          @rename_keyword(deprecation=666, my_old_keyword='my_new_keyword')
+          def my_function(my_new_keyword=True):
+              return my_new_keyword
 
 * **Rename a function/method:** call

but then syntax highlight disappeared from html ouput. So maybe we forgot this, and I try to remember right place for import next time I deprecate something.

comment:15 Changed 5 years ago by mmezzarobba

  • Reviewers set to Marc Mezzarobba
  • Status changed from needs_review to positive_review

comment:16 Changed 5 years ago by vbraun

  • Branch changed from u/jdemeyer/deprecated_function_alias_should_not_appear_in_the_documentation_of_posets to 09c288af4239b36b19e3a3504ced1fe4e5649db6
  • Resolution set to fixed
  • Status changed from positive_review to closed
Note: See TracTickets for help on using tickets.