From ecdf5d872861a07f66e5ac901138bb568ecb7840 Mon Sep 17 00:00:00 2001 From: Rob Young Date: Tue, 29 Aug 2023 08:58:34 +0100 Subject: [PATCH] Refactor the docs to promote user functions The functions that users most often use are the matcher functions, however the docs show the internal matcher classes first. This means that users have to scan through a bunch of internal detail to get to the documentation they're most likely interested in. This change switches things around to just document the actual matcher functions. --- doc/decorator_matchers.rst | 8 ++++---- doc/dictionary_matchers.rst | 14 ++++++++------ doc/logical_matchers.rst | 18 ++++++++---------- doc/number_matchers.rst | 10 ++++++++-- doc/object_matchers.rst | 28 ++++++++++++++++++++-------- doc/sequence_matchers.rst | 28 ++++++++++++---------------- doc/text_matchers.rst | 25 ++++++++++++++++--------- 7 files changed, 76 insertions(+), 55 deletions(-) diff --git a/doc/decorator_matchers.rst b/doc/decorator_matchers.rst index 98b20434..1c92a32c 100644 --- a/doc/decorator_matchers.rst +++ b/doc/decorator_matchers.rst @@ -7,11 +7,11 @@ Matchers that decorate other matchers for better expression. described_as ^^^^^^^^^^^^ -.. automodule:: hamcrest.core.core.described_as - :exclude-members: described_as -.. autofunction:: described_as(description, matcher[, value1[, ...]]) +.. currentmodule:: hamcrest.core.core.described_as +.. autofunction:: described_as is\_ ^^^^ -.. automodule:: hamcrest.core.core.is_ +.. currentmodule:: hamcrest.core.core.is_ +.. autofunction:: is_ diff --git a/doc/dictionary_matchers.rst b/doc/dictionary_matchers.rst index 002ad66b..162fa718 100644 --- a/doc/dictionary_matchers.rst +++ b/doc/dictionary_matchers.rst @@ -7,21 +7,23 @@ Matchers of dictionaries. has_entries ^^^^^^^^^^^ -.. automodule:: hamcrest.library.collection.isdict_containingentries - :exclude-members: has_entries -.. autofunction:: has_entries(matcher_dict) +.. currentmodule:: hamcrest.library.collection.isdict_containingentries +.. autofunction:: has_entries has_entry ^^^^^^^^^ -.. automodule:: hamcrest.library.collection.isdict_containing +.. currentmodule:: hamcrest.library.collection.isdict_containing +.. autofunction:: has_entry has_key ^^^^^^^ -.. automodule:: hamcrest.library.collection.isdict_containingkey +.. currentmodule:: hamcrest.library.collection.isdict_containingkey +.. autofunction:: has_key has_value ^^^^^^^^^ -.. automodule:: hamcrest.library.collection.isdict_containingvalue +.. currentmodule:: hamcrest.library.collection.isdict_containingvalue +.. autofunction:: has_value diff --git a/doc/logical_matchers.rst b/doc/logical_matchers.rst index 35f6f517..b5b7adea 100644 --- a/doc/logical_matchers.rst +++ b/doc/logical_matchers.rst @@ -7,25 +7,23 @@ Boolean logic using other matchers. all_of ^^^^^^ -.. automodule:: hamcrest.core.core.allof - :exclude-members: all_of -.. autofunction:: all_of(matcher1[, matcher2[, ...]]) +.. currentmodule:: hamcrest.core.core.allof +.. autofunction:: all_of any_of ^^^^^^ -.. automodule:: hamcrest.core.core.anyof - :exclude-members: any_of -.. autofunction:: any_of(matcher1[, matcher2[, ...]]) +.. currentmodule:: hamcrest.core.core.anyof +.. autofunction:: any_of anything ^^^^^^^^ -.. automodule:: hamcrest.core.core.isanything - :exclude-members: anything -.. autofunction:: anything([description]) +.. currentmodule:: hamcrest.core.core.isanything +.. autofunction:: anything is_not ^^^^^^ -.. automodule:: hamcrest.core.core.isnot +.. currentmodule:: hamcrest.core.core.isnot +.. autofunction:: is_not diff --git a/doc/number_matchers.rst b/doc/number_matchers.rst index 1cbb2dc8..4906ac19 100644 --- a/doc/number_matchers.rst +++ b/doc/number_matchers.rst @@ -7,9 +7,15 @@ Matchers that perform numeric comparisons. close_to ^^^^^^^^ -.. automodule:: hamcrest.library.number.iscloseto +.. currentmodule:: hamcrest.library.number.iscloseto +.. autofunction:: close_to greater_than, greater_than_or_equal_to, less_than, less_than_or_equal_to ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -.. automodule:: hamcrest.library.number.ordering_comparison +.. currentmodule:: hamcrest.library.number.ordering_comparison +.. autofunction:: greater_than +.. autofunction:: greater_than_or_equal_to +.. autofunction:: less_than +.. autofunction:: less_than_or_equal_to + diff --git a/doc/object_matchers.rst b/doc/object_matchers.rst index 216b5fb6..5dd5d9e8 100644 --- a/doc/object_matchers.rst +++ b/doc/object_matchers.rst @@ -7,39 +7,51 @@ Matchers that inspect objects. equal_to ^^^^^^^^ -.. automodule:: hamcrest.core.core.isequal +.. currentmodule:: hamcrest.core.core.isequal +.. autofunction:: equal_to has_length ^^^^^^^^^^ -.. automodule:: hamcrest.library.object.haslength +.. currentmodule:: hamcrest.library.object.haslength +.. autofunction:: has_length has_string ^^^^^^^^^^ -.. automodule:: hamcrest.library.object.hasstring +.. currentmodule:: hamcrest.library.object.hasstring +.. autofunction:: has_string has_properties/has_property ^^^^^^^^^^^^^^^^^^^^^^^^^^^ -.. automodule:: hamcrest.library.object.hasproperty +.. currentmodule:: hamcrest.library.object.hasproperty +.. autofunction:: has_properties +.. autofunction:: has_property instance_of ^^^^^^^^^^^ -.. automodule:: hamcrest.core.core.isinstanceof +.. currentmodule:: hamcrest.core.core.isinstanceof +.. autofunction:: instance_of none, not_none ^^^^^^^^^^^^^^ -.. automodule:: hamcrest.core.core.isnone +.. currentmodule:: hamcrest.core.core.isnone +.. autofunction:: none +.. autofunction:: not_none + same_instance ^^^^^^^^^^^^^ -.. automodule:: hamcrest.core.core.issame +.. currentmodule:: hamcrest.core.core.issame +.. autofunction:: same_instance calling, raises ^^^^^^^^^^^^^^^ -.. automodule:: hamcrest.core.core.raises +.. currentmodule:: hamcrest.core.core.raises +.. autofunction:: calling +.. autofunction:: raises diff --git a/doc/sequence_matchers.rst b/doc/sequence_matchers.rst index 6913471e..869cb182 100644 --- a/doc/sequence_matchers.rst +++ b/doc/sequence_matchers.rst @@ -7,39 +7,35 @@ Matchers of sequences. contains_exactly ^^^^^^^^^^^^^^^^ -.. automodule:: hamcrest.library.collection.issequence_containinginorder - :exclude-members: contains, contains_exactly -.. autofunction:: contains_exactly(match1, [match2[, ...]]) +.. currentmodule:: hamcrest.library.collection.issequence_containinginorder +.. autofunction:: contains_exactly contains_inanyorder ^^^^^^^^^^^^^^^^^^^ -.. automodule:: hamcrest.library.collection.issequence_containinginanyorder - :exclude-members: contains_inanyorder -.. autofunction:: contains_inanyorder(match1, [match2[, ...]]) +.. currentmodule:: hamcrest.library.collection.issequence_containinginanyorder +.. autofunction:: contains_inanyorder has_item, has_items ^^^^^^^^^^^^^^^^^^^ -.. automodule:: hamcrest.library.collection.issequence_containing - :exclude-members: has_items -.. autofunction:: has_items(match1, [match2[, ...]]) +.. currentmodule:: hamcrest.library.collection.issequence_containing +.. autofunction:: has_items is_in ^^^^^ -.. automodule:: hamcrest.library.collection.isin +.. currentmodule:: hamcrest.library.collection.isin +.. autofunction:: is_in only_contains ^^^^^^^^^^^^^ -.. automodule:: hamcrest.library.collection.issequence_onlycontaining - :exclude-members: only_contains -.. autofunction:: only_contains(match1, [match2[, ...]]) +.. currentmodule:: hamcrest.library.collection.issequence_onlycontaining +.. autofunction:: only_contains empty ^^^^^ -.. automodule:: hamcrest.library.collection.is_empty - :exclude-members: empty -.. autofunction:: empty() +.. currentmodule:: hamcrest.library.collection.is_empty +.. autofunction:: empty diff --git a/doc/text_matchers.rst b/doc/text_matchers.rst index ea715561..83407213 100644 --- a/doc/text_matchers.rst +++ b/doc/text_matchers.rst @@ -7,37 +7,44 @@ Matchers that perform text comparisons. contains_string ^^^^^^^^^^^^^^^ -.. automodule:: hamcrest.library.text.stringcontains +.. currentmodule:: hamcrest.library.text.stringcontains +.. autofunction:: contains_string ends_with ^^^^^^^^^ -.. automodule:: hamcrest.library.text.stringendswith +.. currentmodule:: hamcrest.library.text.stringendswith +.. autofunction:: ends_with + equal_to_ignoring_case ^^^^^^^^^^^^^^^^^^^^^^ -.. automodule:: hamcrest.library.text.isequal_ignoring_case +.. currentmodule:: hamcrest.library.text.isequal_ignoring_case +.. autofunction:: equal_to_ignoring_case + equal_to_ignoring_whitespace ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -.. automodule:: hamcrest.library.text.isequal_ignoring_whitespace +.. currentmodule:: hamcrest.library.text.isequal_ignoring_whitespace +.. autofunction:: equal_to_ignoring_whitespace matches_regexp ^^^^^^^^^^^^^^ -.. automodule:: hamcrest.library.text.stringmatches +.. currentmodule:: hamcrest.library.text.stringmatches +.. autofunction:: matches_regexp starts_with ^^^^^^^^^^^ -.. automodule:: hamcrest.library.text.stringstartswith +.. currentmodule:: hamcrest.library.text.stringstartswith +.. autofunction:: starts_with string_contains_in_order ^^^^^^^^^^^^^^^^^^^^^^^^ -.. automodule:: hamcrest.library.text.stringcontainsinorder - :exclude-members: string_contains_in_order -.. autofunction:: string_contains_in_order(string1[, string2[, ...]]) +.. currentmodule:: hamcrest.library.text.stringcontainsinorder +.. autofunction:: string_contains_in_order