Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

chore: [FC-0074] drop hooks docs in favor of latest in docs.openedx.org #35921

Merged
merged 6 commits into from
Dec 11, 2024
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 5 additions & 3 deletions docs/concepts/extension_points.rst
Original file line number Diff line number Diff line change
Expand Up @@ -139,10 +139,10 @@ Here are the different integration points that python plugins can use:
- This decorator allows overriding any function or method by pointing to an alternative implementation in settings. Read the |pluggable_override docstring|_ to learn more.
* - Open edX Events
- Adopt, Stable
- Events are part of the greater Hooks Extension Framework for open extension of edx-platform. Events are a stable way for plugin developers to react to learner or author events. They are defined by a `separate events library`_ that developers can include in their requirements to develop and test the code without creating a dependency on this large repo. For more information see the `hooks guide`_.
- Events are part of the greater Hooks Extension Framework for open extension of edx-platform. Events are a stable way for plugin developers to react to learner or author events. They are defined by a `separate events library`_ that developers can include in their requirements to develop and test the code without creating a dependency on this large repo. For more information see the `Hooks Extension Framework docs`_ or for more detailed documentation about Open edX Events, see the `Open edX Events documentation`_.
* - Open edX Filters
- Adopt, Stable
- Filters are also part of Hooks Extension Framework for open extension of edx-platform. Filters are a flexible way for plugin developers to modify learner or author application flows. They are defined by a `separate filters library`_ that developers can include in their requirements to develop and test the code without creating a dependency on this large repo. For more information see the `hooks guide`_.
- Filters are also part of Hooks Extension Framework for open extension of edx-platform. Filters are a flexible way for plugin developers to modify learner or author application flows. They are defined by a `separate filters library`_ that developers can include in their requirements to develop and test the code without creating a dependency on this large repo. For more information see the `Hooks Extension Framework docs`_ or for more detailed documentation about Open edX Filters, see the `Open edX Filters documentation`_.

.. _Application: https://docs.djangoproject.com/en/3.0/ref/applications/
.. _Django app plugin documentation: https://github.com/openedx/edx-platform/blob/master/openedx/core/djangoapps/plugins/README.rst
Expand All @@ -159,7 +159,9 @@ Here are the different integration points that python plugins can use:
.. _pluggable_override docstring: https://github.com/openedx/edx-django-utils/blob/master/edx_django_utils/plugins/pluggable_override.py
.. _separate events library: https://github.com/eduNEXT/openedx-events/
.. _separate filters library: https://github.com/eduNEXT/openedx-filters/
.. _hooks guide: https://github.com/openedx/edx-platform/blob/master/docs/guides/hooks/index.rst
.. _Hooks Extension Framework docs: https://docs.openedx.org/en/latest/developers/concepts/hooks_extension_framework.html
.. _Open edX Events documentation: https://docs.openedx.org/projects/openedx-events/en/latest/
.. _Open edX Filters documentation: https://docs.openedx.org/projects/openedx-filters/en/latest/

Platform Look & Feel
====================
Expand Down
11 changes: 11 additions & 0 deletions docs/conf.py
Original file line number Diff line number Diff line change
Expand Up @@ -68,6 +68,7 @@
'code_annotations.contrib.sphinx.extensions.featuretoggles',
'code_annotations.contrib.sphinx.extensions.settings',
# 'autoapi.extension', # Temporarily disabled
'sphinx_reredirects',
]

# Temporarily disabling autoapi_dirs and the AutoAPI extension due to performance issues.
Expand Down Expand Up @@ -304,6 +305,16 @@
# 'xmodule': 'references/docstrings/xmodule',
}

# Mapping permanently moved pages to appropriate new location outside of edx-platform
# with by sphinx-reredirects extension redirects.
# More information: https://documatt.com/sphinx-reredirects/usage.html

redirects = {
'hooks/events': 'https://docs.openedx.org/projects/openedx-events/en/latest/',
'hooks/filters': 'https://docs.openedx.org/projects/openedx-filters/en/latest/',
'hooks/index': 'https://docs.openedx.org/en/latest/developers/concepts/hooks_extension_framework.html',
}


def update_settings_module(service='lms'):
"""
Expand Down
261 changes: 0 additions & 261 deletions docs/hooks/events.rst
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Also, I think @feanil has added redirects for deleted docs in certain cases. That may be an option, but you are in a better position to determine whether it is worth it.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think redirects would be good, @feanil if you can let us know the best way to do that

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We use sphinx-reredirects for setting up redirects, they can be added to the conf.py : https://documatt.com/sphinx-reredirects/usage.html

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Will do. Thank you!

Copy link
Member Author

@mariajgrimaldi mariajgrimaldi Nov 26, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Here's the suggested change: d3b3787. I can't ensure whether this configuration works correctly, so I'm generating docs locally to check. Thank you!

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Do you know if there's a way to build these docs remotely? I'm not sure either if there's a way of testing these redirects independently without building the entire docs. It took an hour for my computer to kill the building process because it ran out of memory. I'm currently using the latest changes in master which fix the issues with sphinx resource consumption, but still :/

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

There is an issue currently that is causing the docs build to fail that @irtazaakram is looking at. Hopefully that will be fixed soon and you'll be able to build locally.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks, @feanil! I could build the docs locally to test this out. Here's what I tested:

/hooks -> redirects to the new hooks docs
/hooks/events.html -> redirects to the new events docs
/hooks/filters.html -> redirects to the new filters docs

However, references to :doc:hooks/index won't work/ I'm guessing because those documents with the metadata to redirect are available after building, so sphinx doesn't find them. Instead, I added references to the new URLs here: 7e50063

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think that's fine for now, it looks like we don't have intersphinx setup to connect between this and the upstream docs so I think this can merge as is.

This file was deleted.

Loading
Loading