Skip to content

Docs: remove outdated and complex code and dependencies #9981

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

Merged

Conversation

humitos
Copy link
Member

@humitos humitos commented Feb 2, 2023

This commit reduces the complexity of the documentation environment by removing the requirement of having Django installed and loaded to build the docs.

  • Remove the djangodocs and doc_extensions: they load the whole Django application unnecesarily. We need to have a bunch of requirements installed just because of this.

  • Remove defaults from "Interesting settings" because all the default were wrong. The Django extension was loading an invalid set of settings. This page could be completely removed as well probably.

  • Remove featureflag role because of the same reason (loads a whole Django project). We were using it only to show a small description of the feature flags. I wrote that text directly in the page. Feature flags are deprecated and this page will probably deleted soon as well.

  • Remove buildpyversions role also. Same reason. Manually wrote the versions supported on each Docker image. This is used for the legacy images, tho. They won't change since we don't maintain them anymore.

Since we don't depend on Django anymore we can remove the -r pip.txt dependency from the documentation. This makes the documentation just to rely on Sphinx and some other extensions only simplifying the environment a lot and running fast.

My thinking behind all of this was that it is not worth to maintain such a complex environment and tools just to be able to output the "default values" from some Django settings in the documentation. In particular, if these defaults are not really useful for our users. Even more, if the default values we are showing to them are wrong and don't reflect the real ones when using the Docker development environment 🙃

NOTE: this branch is based on #9978 because I found this problem while working on that setting simplification. Merging this PR will make #9978 to pass the tests.


📚 Documentation previews 📚

This commit reduces the complexity of the documentation environment by removing
the requirement of having Django installed and loaded to build the docs.

* Remove the `djangodocs` and `doc_extensions`: they load the whole Django
application unnecesarily. We need to have a bunch of requirements installed just
because of this.

* Remove defaults from "Interesting settings" because all the default were
wrong. The Django extension was loading an invalid set of settings. This page
could be completely removed as well probably.

* Remove `featureflag` role because of the same reason (loads a whole Django
project). We were using it only to show a small description of the feature
flags. I wrote that text directly in the page. Feature flags are deprecated and
this page will probably deleted soon as well.

* Remove `buildpyversions` role also. Same reason. Manually wrote the versions
supported on each Docker image. This is used for the legacy images, tho. They
won't change since we don't maintain them anymore.
Since we don't depend on Django anymore we can remove the `-r pip.txt`
dependency from the documentation.

This makes the documentation just to rely on Sphinx and some other extensions
only simplifying the environment a lot and running fast.
@humitos humitos requested review from a team as code owners February 2, 2023 20:06
@humitos humitos requested a review from benjaoming February 2, 2023 20:06
@humitos humitos changed the title Docs: remove outdated and complex code Docs: remove outdated and complex code and dependencies Feb 2, 2023
@humitos humitos requested a review from ericholscher February 2, 2023 20:13
Copy link
Member

@ericholscher ericholscher left a comment

Choose a reason for hiding this comment

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

This makes a bunch of sense to me. I've never been a huge fan of these dynamic features given how little we use them.

If we want dynamic stuff like this, it would be much better to build this functionality into our platform, so we can do more dynamic things via an API, and update that data eg; on deploy or merge to main.

But, I think we'd all agree that is likely not super important unless we have a lot of users requesting it, and can just move forward with static information in the docs 👍

@@ -1,7 +1,6 @@
# Packages required to build docs, independent of application dependencies

-r pip.txt

sphinx
Copy link
Member

Choose a reason for hiding this comment

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

😍

@humitos humitos merged commit 50147a1 into humitos/settings-simplification Feb 3, 2023
@humitos humitos deleted the humitos/simplify-docs-building branch February 3, 2023 06:08
@benjaoming
Copy link
Contributor

THANK YOU 🙏

This will be a big benefit for current documentation efforts!

humitos added a commit that referenced this pull request Feb 7, 2023
#9978)

* Settings: simplify all the settings removing a whole old layer (`dev`)

We are not using `settings/dev.py` since we started using
Docker (`settings/docker_compose.py`).
However, we never updated this code.

This commit removes the extra `Dev` class layer by moving the required (and
still used settings) into `settings/test.py` and `settings/docker_compose.py`
since they were inheriting from `settings/dev.py`.

* Settings: add missing setting for test

* Settings: missing on web

* Setting: missing on celery

* Settings: missing on proxito

* Settings: updates for docs/

* Docs: remove outdated and complex code and dependencies (#9981)

* Docs: remove outdated and complex code

This commit reduces the complexity of the documentation environment by removing
the requirement of having Django installed and loaded to build the docs.

* Remove the `djangodocs` and `doc_extensions`: they load the whole Django
application unnecesarily. We need to have a bunch of requirements installed just
because of this.

* Remove defaults from "Interesting settings" because all the default were
wrong. The Django extension was loading an invalid set of settings. This page
could be completely removed as well probably.

* Remove `featureflag` role because of the same reason (loads a whole Django
project). We were using it only to show a small description of the feature
flags. I wrote that text directly in the page. Feature flags are deprecated and
this page will probably deleted soon as well.

* Remove `buildpyversions` role also. Same reason. Manually wrote the versions
supported on each Docker image. This is used for the legacy images, tho. They
won't change since we don't maintain them anymore.

* Docs: reduce requirements drastically

Since we don't depend on Django anymore we can remove the `-r pip.txt`
dependency from the documentation.

This makes the documentation just to rely on Sphinx and some other extensions
only simplifying the environment a lot and running fast.

* Docs: don't install `pip.txt`

* Docs: remove missing `djangosetting` role

* Solve minimal merge conflicts
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3 participants