docs: add newest docs for openedx-filters #64

mariajgrimaldi · 2023-01-26T15:42:02Z

Description

This PR adds the latest documentation for Open edX Filters usage.

openedx-webhooks · 2023-01-26T15:42:08Z

Thanks for the pull request, @mariajgrimaldi!

As a core committer in this repo, you can merge this once the pull request is approved per the core committer reviewer requirements and according to the agreement with your edX Champion.

mphilbrick211 · 2023-06-01T14:24:03Z

Hey @mariajgrimaldi :) Just checking to see if you plan to pursue this one?

feanil · 2023-06-02T17:44:45Z

@mariajgrimaldi I looked through the content you already put in here and it was very valuable, I'd love for you or other filters users to flesh out the rest of this tree that you built. I went ahead and wired everything together so the docs build is green. Are there other things we can do to help with this.

@openedx/arch-bom do you have any knowledge in this area of extensibility that you could use to help build out some of these docs?

mariajgrimaldi · 2023-06-06T15:34:48Z

@feanil thank you so much! I will write at least the minimum info needed for a 1st version so we can deploy it and iterate over it! I already blocked a slot in my calendar to do it. I'll let you know once I'm done so you folks can review it!

mariajgrimaldi · 2023-06-28T22:22:54Z

note: we can add specifications about filters associated with the template rendering process, which are a bit different from the usual filters. We can also add a list of filters, like the index from edx-platform, but with descriptions and possible use cases.

feanil

@mariajgrimaldi changes look great! Lots of awesome details, I have a few suggestions to add clarity but overall this looks great!

docs/concepts/hooks-extension-framework.rst

feanil · 2023-06-30T16:32:56Z

docs/how-tos/create-new-filter.rst

+- The ``run_filter`` class method calls the ``run_pipeline`` method, which is the method that executes the filter's logic. This method is defined in the ``OpenEdxPublicFilter`` class, which is the base class for all the filters in the library. This method returns a dictionary with the following structure:
+
+    .. code-block:: python
+
+      {
+        "form_data": form_data,
+      }
+
+    Where ``form_data`` is the same set of parameters that the filter receives, which is the accumulated output for the filter's pipeline. This is how ``run_filter`` should always look like.


This bullet point is a bit confusing. I think what you're saying is that for this specific filter, the run_pipeline method will return the dictionary with form_data in it. But in general what is return is up to the specific filter type? Is that right?

Yes! That's right. I'm adding a clarifying example.

I changed this up a bit too: https://github.com/openedx/openedx-filters/pull/64/files#diff-a563d883eb42de51f7d285e78ba100247246d9d33cf71829b752ece0b7f5de6aR132-R151

feanil · 2023-06-30T16:38:21Z

docs/how-tos/using-filters.rst

+1. The filter step must be a subclass of ``PipelineStep``.
+
+2. The ``run_filter`` signature must match the filters definition, eg.,
+the previous step matches the method's definition in CertificateCreationRequested.


suggestion: It might be useful to put a copy of the filter definition here so that readers can see how the signature in the PipelineStep maps to the signature of the run_filter in the filter definition. Because when you say the filters definition it's not clear if you mean the signature of run_pipeline or of run_filter in the filter definition.

I rephrased it and added the filter definition: https://github.com/openedx/openedx-filters/pull/64/files#diff-2f00ad15852db823832ebd7a824f9a50eb845116051e7e9c64e99aa0721db8d5R41-R81

docs/how-tos/using-filters.rst

docs/reference/django-plugins-and-filters.rst

mphilbrick211 · 2023-07-17T22:42:52Z

Hi @mariajgrimaldi - just following up on this!

feanil

@mariajgrimaldi this is looking great, I had a few small suggestions but then the how-tos for creating and using filters seem good enough to land. I see you have a couple of quickstarts that are still in progress, do you want to do those in a follow-up PR so we can land the pieces that already seem like they're nearly done.

feanil · 2023-07-25T16:36:27Z

docs/concepts/glossary.rst

+Filter signature
+----------------
+
+It's the signature of the `run_filter` method. It defines the input and output of the filter. The input is a dictionary with the data to be processed and the output is a dictionary with the processed data.


Since both the PipelineStep and Open edX Filter class implement a run_filter function which do you mean here? Do both of them have the same signature, it would be good to clarify that in this glossary item.

Mmm I'll better rephrase this then! Thanks

feanil · 2023-07-25T16:44:14Z

docs/quickstarts/use-filters-to-change-enrollment.rst

@@ -0,0 +1,11 @@
+Using Open edX Filters in the LMS service
+=========================================


This document should follow standard heading order as defined here: https://docs.openedx.org/en/latest/documentors/references/quick_reference_rst.html#headings

Thanks! I'll change it

Also drop the changelog from the long description. The way it is right now, that will never succeed the strict checks becaause of the way setuptools currently parses the RST. It generates implicit labels for all headings by default and then it complains when there are duplicates. This will always happen with changelogs because the sub-headings under a changelog entry will always be one of a small set of values (added, fixed, etc.)

openedx-webhooks · 2023-08-14T18:51:44Z

Thanks for the pull request, @mariajgrimaldi! Please note that it may take us up to several weeks or months to complete a review and merge your PR.

Feel free to add as much of the following information to the ticket as you can:

supporting documentation
Open edX discussion forum threads
timeline information ("this must be merged by XX date", and why that is)
partner information ("this is a course on edx.org")
any other information that can help Product understand the context for the PR

All technical communication about the code itself will be done via the GitHub pull request interface. As a reminder, our process documentation is here.

Please let us know once your PR is ready for our review and all tests are green.

mariajgrimaldi · 2023-08-14T18:52:25Z

@feanil: last changes! Let me know what you think

feanil · 2023-08-14T20:30:40Z

Looks great! Thanks for all the hard work on this @mariajgrimaldi !

mariajgrimaldi · 2023-08-22T12:46:53Z

I'll be merging this now! Thank you folks!

openedx-webhooks · 2023-08-22T12:47:50Z

@mariajgrimaldi 🎉 Your pull request was merged! Please take a moment to answer a two question survey so we can improve your experience in the future.

openedx-webhooks added core committer open-source-contribution PR author is not from Axim or 2U labels Jan 26, 2023

mariajgrimaldi force-pushed the MJG/filers-docs branch from e2c2ef4 to 8bad482 Compare January 26, 2023 15:55

mariajgrimaldi force-pushed the MJG/update-docs branch from 81ee4f5 to d5bb00c Compare February 7, 2023 22:01

Base automatically changed from MJG/update-docs to main February 7, 2023 22:25

mariajgrimaldi force-pushed the MJG/filers-docs branch from 8bad482 to 4fe2795 Compare February 20, 2023 15:59

feanil force-pushed the MJG/filers-docs branch from d6c493b to 239125a Compare June 2, 2023 14:22

mariajgrimaldi mentioned this pull request Jun 6, 2023

docs: use new standard Open edX for documentation #63

Merged

10 tasks

mariajgrimaldi changed the title ~~feat: fill in outline for new docs~~ docs: add newest docs for openedx-filters Jun 28, 2023

mariajgrimaldi force-pushed the MJG/filers-docs branch from 44d8950 to 7e025ad Compare June 28, 2023 21:31

mariajgrimaldi marked this pull request as ready for review June 28, 2023 21:32

mariajgrimaldi requested a review from a team as a code owner June 28, 2023 21:32

mariajgrimaldi requested a review from feanil June 28, 2023 22:21

feanil requested changes Jun 30, 2023

View reviewed changes

mariajgrimaldi requested a review from feanil July 24, 2023 15:23

feanil reviewed Jul 25, 2023

View reviewed changes

mariajgrimaldi and others added 8 commits August 14, 2023 14:51

feat: fill in outline for new docs

035feb5

docs: rearranging docs with most important information

0f3e00b

docs: add missing file for creating a filter

0e3d238

docs: Add more skeleton so that docs build succeeds.

1528ca3

docs: add documentation for current filters tooling

3346c7d

refactor: address PR reviews

6d88a45

refactor: address PR reviews

20d484a

mariajgrimaldi force-pushed the MJG/filers-docs branch from b0c9830 to 20d484a Compare August 14, 2023 18:51

feanil approved these changes Aug 14, 2023

View reviewed changes

mariajgrimaldi merged commit 70d3fb1 into main Aug 22, 2023
6 checks passed

mariajgrimaldi deleted the MJG/filers-docs branch August 22, 2023 12:47

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs: add newest docs for openedx-filters #64

docs: add newest docs for openedx-filters #64

mariajgrimaldi commented Jan 26, 2023 •

edited

Loading

openedx-webhooks commented Jan 26, 2023 •

edited

Loading

mphilbrick211 commented Jun 1, 2023

feanil commented Jun 2, 2023

mariajgrimaldi commented Jun 6, 2023

mariajgrimaldi commented Jun 28, 2023

feanil left a comment

feanil Jun 30, 2023

mariajgrimaldi Jul 18, 2023

mariajgrimaldi Jul 18, 2023

feanil Jun 30, 2023

mariajgrimaldi Jul 18, 2023

mphilbrick211 commented Jul 17, 2023

feanil left a comment

feanil Jul 25, 2023

mariajgrimaldi Jul 27, 2023

feanil Jul 25, 2023

mariajgrimaldi Jul 27, 2023

openedx-webhooks commented Aug 14, 2023

mariajgrimaldi commented Aug 14, 2023

feanil commented Aug 14, 2023

mariajgrimaldi commented Aug 22, 2023

openedx-webhooks commented Aug 22, 2023

		@@ -0,0 +1,11 @@
		Using Open edX Filters in the LMS service
		=========================================

docs: add newest docs for openedx-filters #64

docs: add newest docs for openedx-filters #64

Conversation

mariajgrimaldi commented Jan 26, 2023 • edited Loading

Description

openedx-webhooks commented Jan 26, 2023 • edited Loading

mphilbrick211 commented Jun 1, 2023

feanil commented Jun 2, 2023

mariajgrimaldi commented Jun 6, 2023

mariajgrimaldi commented Jun 28, 2023

feanil left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

mphilbrick211 commented Jul 17, 2023

feanil left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

openedx-webhooks commented Aug 14, 2023

mariajgrimaldi commented Aug 14, 2023

feanil commented Aug 14, 2023

mariajgrimaldi commented Aug 22, 2023

openedx-webhooks commented Aug 22, 2023

mariajgrimaldi commented Jan 26, 2023 •

edited

Loading

openedx-webhooks commented Jan 26, 2023 •

edited

Loading