Skip to content

Design doc: new builder with explicit options #8103

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.

Sign up for GitHub

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

Closed
wants to merge 2 commits into from
Closed

Design doc: new builder with explicit options #8103

Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
29ba47a
Design doc: new builder with explicit options
stsewd Apr 13, 2021
47f29ac
Update
stsewd Apr 15, 2021
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
37 changes: 31 additions & 6 deletions docs/development/design/explicit-builders.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -57,7 +57,8 @@ We would need to refactor those classes into two types: the new build, and the o

Both builders create an ``index.{rst,md}`` file with some suggestions if one doesn't exist,
this is to avoid surprises to users, but sometimes this is done on purpose.
We could change our default 404 page to include some of these suggestions instead.
We could change our default 404 page to include some of these suggestions instead,
or fail the build if there isn't an ``index.html`` file created (do users want to do this on purpose?).
Related to `#1800`_.

.. _#1800: https://github.com/readthedocs/readthedocs.org/issues/1800
Expand Down Expand Up @@ -101,6 +102,7 @@ Extension

There are some things our extension does that are already supported by Sphinx or themes
(analytics, canonical URL, etc), we should write a guide instead of applying our magic.
Alternative, we can make this options, analytics is already an option.

The extension also injects some custom js and css files.
We could try another more general approach and inject these on each HTML file after the build is complete.
Copy link
Member

Choose a reason for hiding this comment

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

This approach makes sense if we are going to support other building tools in the future. This will probably have some impact on big projects with many HTML files, since we will need to rewrite all of them.

Copy link
Member

Choose a reason for hiding this comment

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

Yea, I think adjusting the built HTML is the right way to handle this, so we can support non-Sphinx builders. In mkdocs we're just adding this to their setting:

readthedocs.org/readthedocs/doc_builder/backends/mkdocs.py

Lines 175 to 178 in 924699c

user_config.setdefault('extra_javascript', []).extend(
[js for js in extra_javascript_list if js not in user_config.get(
'extra_javascript')]
)

But it seems like explicitly doing it after build against all HTML is more extensible.

Copy link
Member

@ericholscher ericholscher May 13, 2021 •
edited
Loading

Choose a reason for hiding this comment

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

Breaking it out from the extension into the build process is probably correct here. 👍

Expand Down Expand Up @@ -153,17 +155,18 @@ Some are:

Other settings are used for things that can be done from the user side:

- Analytics code
- Canonical domain (Sphinx only)
- Analytics code (exposed as an option)
- Canonical domain (Sphinx only, and isn't exposed as an option)

Adoption
--------

If we remove some magical behaviour that was doing things for the user,
we should document how to do them using Sphinx/MkDocs.

These new builders/environments would be under a feature flag,
where projects created after ``x`` date would use the new builders and environments,
These new builders/environments would be under a feature flag.
We can keep the implementation incrementally by start using a feature flag on some of our projects first,
after we everything is implemented we can move the flag to be active for projects created after ``x`` date,
and past projects would use the old ones.

Deprecation
Expand All @@ -175,4 +178,26 @@ and other after that date. We can opt-in users into the new builders by adding t
In order to simplify our code and have all projects using the same options and dependencies
we want to fully migrate all projects to use the new builders.
We could put a date to do this, and contact all users of old projects about this change
(an entry in our blog would also be nice).
Some things to do would be:

- Write several guides on how to do things explicitly
- Write several guides on how users can implement the magic things we were doing
(canonical domain, analytics, custom theme, dependencies, PDF improvements for Japanese and Chinese languages, etc)
- An entry in our blog
- Email all users that have old projects
- Give users some time to migrate (six months, one year?)
- Migrate all projects to the new builders
(allow users to opt-in into the old builders with a feature flag for a short time in case they didn't get to migrate? Could be useful for commercial)
- Remove old code

The future
----------

We may also take this as an opportunity to get ready to support more tools,
this is by depending less on overrides and extensions, and work over the generated HTML.

For Sphinx, it could be useful to implement our new context :doc:`/development/design/theme-context`,
but do we really need to inject that context anymore? We have API v3 now.

As proposed, we can make this changes incrementally and test in our own projects before
making the final decisions.