Added available sort options for all REST API endpoints that allow sorting #612

monotasker · 2024-03-26T20:39:58Z

❤️ Thank you for your contribution!

Description

Added documentation on the sort options available for all REST API endpoints that allow sorting.

Checklist

Ticks in all boxes and 🟢 on all GitHub actions status checks are required to merge:

[X ] I'm aware of the code of conduct.
[X ] I've created logical separate commits and followed the commit message format.
[X ] I've added relevant test cases.
[X ] I've added relevant documentation.
[X ] I've marked translation strings (for relevant code).
[X ] I've followed the CSS/JS and React guidelines (for relevant code).
[X ] I've followed the web accessibility guidelines (for relevant code).
[X ] I've followed the user interface guidelines (for relevant code).
[X ] I've identified the copyright holder(s) and updated copyright headers for touched files (>15 lines contributions).
[X ] I've NOT included third-party code (copy/pasted source code or new dependencies).

Third-party code

If you've added third-party code (copy/pasted or new dependencies), please reach out to an architect.

Reminder

By using GitHub, you have already agreed to the GitHub’s Terms of Service including that:

You license your contribution under the same terms as the current repository’s license.
You agree that you have the right to license your contribution under the current repository’s license.

fenekku

Thanks for these, really appreciate you documenting that special sorting logic we have. Just some minor things, but worth aligning on subjects + no need for general sort section (I think) before merging.

docs/reference/rest_api_awards.md

docs/reference/rest_api_communities.md

fenekku · 2024-03-27T12:42:24Z

docs/reference/rest_api_vocabularies.md

+The sort options available vary depending on the vocabulary being searched. These cannot presently be configured via config variables but are set in the service configuration for each vocabulary service. The default sort options are used where a vocabulary service has not defined its own:
+
+| Vocabulary | Available sort options | Default | Default without a query string |
+| ---------- | ---------------------- | ------- | ------------------------------ |
+| default | `"bestmatch"`, `"title"`, `"newest"`, `"oldest"` | `"bestmatch"` | `"title"` |
+| affiliations | `"bestmatch"`, `"name"`, `"newest"`, `"oldest"` | `"bestmatch"` | `"name"` |
+| awards | `"bestmatch"`, `"title"`, `"newest"`, `"oldest"` | `"bestmatch"` | `"title"` |
+| funders | `"bestmatch"`, `"name"`, `"newest"`, `"oldest"` | `"bestmatch"` | `"name"` |
+| names | `"bestmatch"`, `"name"`, `"newest"`, `"oldest"` | `"bestmatch"` | `"name"` |
+| subjects* | `"bestmatch"`, `"subject"`, `"newest"`, `"oldest"` | `"bestmatch"` | `"subject"` |
+
+(\* Subjects are available only at the `/api/subjects` endpoint, but are included here for reference since they are provided by a vocabulary service.)
+<!--Maybe the subjects sort options should be moved to documentation for the `api/subjects` endpoint-->


I think this repeats information given in the specific vocabularies REST API documentation so I wouldn't include it.

We are indeed missing a rest_api_subjects.md documentation page. I've created a ticket for this: #613 and we can deal with it separately there 👍 .

Makes sense. I'll make sure the order is flipped on all the endpoints. Then I'll remove the table and just document the default sort options. I think it's still useful to have the defaults documented, since not all vocabularies have their own endpoint.

Co-authored-by: Guillaume Viger <fenekku@fenekku.com>

fenekku

Just the failing tests to fix and we are good to merge 😄

fenekku · 2024-03-27T19:02:05Z

docs/reference/rest_api_communities.md

 | `size`   | integer | query    | Specify number of items in the results page (default: 10).                                                                                                                                                 |
 | `page`   | integer | query    | Specify the page of results.                                                                                                                                                                               |
 | `type`   | string  | query    | Specify community type as one of organization, event, topic or project.                                                                                                                                    |
 | `accept` | string  | header   | - `application/json` (default)<br />- `application/vnd.inveniordm.v1+json`                                                                                                                                 |

+Sort options for communities can be configured using the `COMMUNITIES_SORT_OPTIONS` config variable as described in the [search customization](../customize/search) section. Note that `"bestmatch"` is only available as a sort option on requests that provide a query string as a `q` parameter. Otherwise `"bestmatch"` is ignored and the default `"newest"` sort is used.


The failing tests are because the links have to be to the markdown files. Mkdocs then takes care of converting them to regular files. So we have to replace:

Suggested change

Sort options for communities can be configured using the `COMMUNITIES_SORT_OPTIONS` config variable as described in the [search customization](../customize/search) section. Note that `"bestmatch"` is only available as a sort option on requests that provide a query string as a `q` parameter. Otherwise `"bestmatch"` is ignored and the default `"newest"` sort is used.

Sort options for communities can be configured using the `COMMUNITIES_SORT_OPTIONS` config variable as described in the [search customization](../customize/search.md) section. Note that `"bestmatch"` is only available as a sort option on requests that provide a query string as a `q` parameter. Otherwise `"bestmatch"` is ignored and the default `"newest"` sort is used.

and then we should be fine 🤞 .

Ah, right. Thanks

monotasker · 2024-04-06T15:16:56Z

Okay, I've made the minor changes to default option ordering, removed the table of vocab options (leaving a description of the defaults), and fixed the missing file extensions in the links. Should be good to go.

fenekku · 2024-04-08T12:23:22Z

Hmm something is off with the links (see https://github.com/inveniosoftware/docs-invenio-rdm/actions/runs/8582061590/job/23563183805?pr=612), but at least one other PR is potentially affected: https://github.com/inveniosoftware/docs-invenio-rdm/actions/runs/8526851030/job/23356983728?pr=614 ... I will add this as something I will look into this month as part of preparations for v12 since we need to make sure docs are good. Can you rebase it to see if that fixes it?

Co-authored-by: Guillaume Viger <fenekku@fenekku.com>

monotasker · 2024-04-08T19:57:24Z

Okay, I rebased my branch but it doesn't seem to have fixed the issue. When I build the docs locally I get the same error: not from links in the documentation text but because of two missing style files: /assets/stylesheets/main.10ba22f1.min.css and /assets/stylesheets/palette.06af60db.min.css. These are linked in the frontpage_base.html template, and the files do indeed seem to be missing. I don't think this is related to any of my changes. Maybe something happened upstream that is just becoming visible here? (Or maybe I'm missing something!)

fenekku · 2024-04-08T20:28:05Z

Indeed something is strange. If you don't mind, when I look into it, may I push to your branch to fix it? This will be faster and you've already done the heavy lifting, so you shouldn't have to deal with that structural problem 😉 .

monotasker · 2024-04-08T20:29:25Z

Sure. No problem

fenekku · 2024-04-10T19:34:52Z

Merged it here: #619 (@monotasker 's master branch is probably protected so I couldn't push to it). I think Nico fixed the issue by resetting the clean options: c6e7334#diff-1db27d93186e46d3b441ece35801b244db8ee144ff1405ca27a163bfe878957fR41 . Kind of strange nevertheless.

Thank you!

Added available sort options for all REST API queries that allow sorting

0958f65

fenekku reviewed Mar 27, 2024

View reviewed changes

monotasker and others added 3 commits March 27, 2024 12:11

Update docs/reference/rest_api_awards.md

21c89e3

Co-authored-by: Guillaume Viger <fenekku@fenekku.com>

Update docs/reference/rest_api_communities.md

ef6441a

Co-authored-by: Guillaume Viger <fenekku@fenekku.com>

Update docs/reference/rest_api_communities.md

2e3f5de

Co-authored-by: Guillaume Viger <fenekku@fenekku.com>

fenekku reviewed Mar 27, 2024

View reviewed changes

monotasker added 2 commits April 6, 2024 11:03

Minor fixes to default orders and link syntax

522dc6c

Merge branch 'master' of github.com:MESH-Research/docs-invenio-rdm

01bc6c5

monotasker and others added 3 commits April 8, 2024 14:54

Update docs/reference/rest_api_awards.md

02edf8e

Co-authored-by: Guillaume Viger <fenekku@fenekku.com>

Fixing merge conflict for rebase

161087f

Fixing merge conflict for rebase

f177f99

Fixed two regressions that arose from the merge process during rebase.

c3915c9

fenekku mentioned this pull request Apr 10, 2024

Transfer of https://github.com/inveniosoftware/docs-invenio-rdm/pull/612 #619

Merged

fenekku closed this Apr 10, 2024

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Added available sort options for all REST API endpoints that allow sorting #612

Added available sort options for all REST API endpoints that allow sorting #612

monotasker commented Mar 26, 2024

fenekku left a comment

fenekku Mar 27, 2024

monotasker Mar 27, 2024

fenekku left a comment

fenekku Mar 27, 2024

monotasker Mar 27, 2024

monotasker commented Apr 6, 2024

fenekku commented Apr 8, 2024 •

edited

Loading

monotasker commented Apr 8, 2024 •

edited

Loading

fenekku commented Apr 8, 2024

monotasker commented Apr 8, 2024

fenekku commented Apr 10, 2024 •

edited

Loading

	Sort options for communities can be configured using the `COMMUNITIES_SORT_OPTIONS` config variable as described in the [search customization](../customize/search) section. Note that `"bestmatch"` is only available as a sort option on requests that provide a query string as a `q` parameter. Otherwise `"bestmatch"` is ignored and the default `"newest"` sort is used.
	Sort options for communities can be configured using the `COMMUNITIES_SORT_OPTIONS` config variable as described in the [search customization](../customize/search.md) section. Note that `"bestmatch"` is only available as a sort option on requests that provide a query string as a `q` parameter. Otherwise `"bestmatch"` is ignored and the default `"newest"` sort is used.

Added available sort options for all REST API endpoints that allow sorting #612

Added available sort options for all REST API endpoints that allow sorting #612

Conversation

monotasker commented Mar 26, 2024

Description

Checklist

fenekku left a comment

Choose a reason for hiding this comment

fenekku Mar 27, 2024

Choose a reason for hiding this comment

monotasker Mar 27, 2024

Choose a reason for hiding this comment

fenekku left a comment

Choose a reason for hiding this comment

fenekku Mar 27, 2024

Choose a reason for hiding this comment

monotasker Mar 27, 2024

Choose a reason for hiding this comment

monotasker commented Apr 6, 2024

fenekku commented Apr 8, 2024 • edited Loading

monotasker commented Apr 8, 2024 • edited Loading

fenekku commented Apr 8, 2024

monotasker commented Apr 8, 2024

fenekku commented Apr 10, 2024 • edited Loading

fenekku commented Apr 8, 2024 •

edited

Loading

monotasker commented Apr 8, 2024 •

edited

Loading

fenekku commented Apr 10, 2024 •

edited

Loading