Docs: hosting integrations for build.commands
#9755
Conversation
Initial file to start documenting hosting integrations. Related #9036 Related readthedocs/meta#71 Related readthedocs/meta#35
humitos
force-pushed
the
humitos/build-commands-integrations
branch
from
3e41f22 to
3efaaa7
Compare
There was a problem hiding this comment.
This looks like a great start. I think we can probably document this, but then have the goal to have the next step be to wrap all this up so you just need a single JS file that pulls the rest of that stuff in. 👍
I do think we need to figure out our plans for #9063 here as well, since we might be injecting that JS file automatically for users as part of v2 🤔
| Level up your search by providing immediate feedback while the user is typing. | ||
| Read more at :doc:`advanced-search.html#enable-search-as-you-type-in-your-documentation`. | ||
|
|
||
| `Version warning`_ |
There was a problem hiding this comment.
Hrm, I thought we had an extension for this?
There was a problem hiding this comment.
We have a core feature that handles the common use case and a Sphinx extension that's more configurable. However, IIRC it broke some time ago due to CORS changes.
There was a problem hiding this comment.
I know this is a draft, so I want to just leave a few general inputs :)
-
I think that this is explanation? In this regard, we should consider moving it out of the
guides/folder because that folder is mostly How-to. It would make a lot of sense if you already now suggest a folder for explanation, perhaps it's as easy asexplanation/? (none of the current iterations have any proposals on where to put explanation) -
Start the section by writing what it is about. This might be shortened later, but it's really helpful in the beginning.
-
Flyout menu: The word "Flyout" is super weird. I've put it in actual quotes in some page titles. Even what it refers to is confusing to me :D
A flyout occurs when a batter hits the ball in the air (not including balls designated as line drives) and an opposing defender catches it before it hits the ground or fence.
❓ 😕
If you happen to think of something, please say so.. already in Iteration 1 #9746 we are looking at the pages about "Flyout" menus.
You've started explaining the "Flyout" menu already in a subsection, so that might also be a reason to coordinate things closely. Otherwise, this work might be easier in Iteration 3 or 4 when we have wrestled with the existing contents and have started to focus more on developing new content.
|
@ericholscher I updated this page a little more adding more explanations for some of the other features. I added some notes to consider/discuss/talk about because telling people to "include this chunk of HTML" won't work for some features (e.g. version warning). I think it is still fine to communicate "what we do", but I don't think it works as "integrate these features in your doctool" yet. IMO, we are not there yet and we should decouple them from being Sphinx extensions and migrate them into a Javascript library that does all this work (for the version warning example, adds the HTML, put the CSS to make it sticky at the top, generate the correct links, etc). Writing this document is being a good exercise to realize what is required to make it fully compatible and generic enough, 💯 |
| Flyout menu | ||
| ----------- | ||
|
|
||
| Displying the flyout menu requires adding some Javascript and CSS files in each of the documentation pages. |
There was a problem hiding this comment.
| Displying the flyout menu requires adding some Javascript and CSS files in each of the documentation pages. | |
| Displaying the flyout menu requires adding some JavaScript and CSS files in each of the documentation pages. |
| External (pull request) version warning | ||
| --------------------------------------- | ||
|
|
||
| On each build built from a pull requests, |
There was a problem hiding this comment.
| On each build built from a pull requests, | |
| For each :ref:`pull request <pull-requests:Preview Documentation from Pull Requests>`, |
|
@benjaoming Flyout is a standard term for what we're doing.. https://elementor.com/resources/glossary/what-is-flyout-navigation/ |
|
Good reference to know. It'd still be interesting to figure out a better name. For now, I think we should resort to be careful to always mention it with a definition or reference. To me as a reader, the word "flyout" is kind of alienating if it doesn't come with a definition or reference. |
|
@benjaoming Yea, I think in general we try to |
I'm suggesting our Javascript library should inject these things in a floating/sticky way because they don't break the HTML structure. Take a look at how Flask does this: https://flask.palletsprojects.com/en/1.0.x/
|
|
📓 Note to myself:
We need to explain here how this works and where this is injected? How do we plan this to work on non-Sphinx projects? |
|
I'm closing this PR for now since is superseded by #10127. The important conversation will be happening there. |
Initial file to start documenting hosting integrations.
This is not ready to review or merge. I'm just pushing this changes to ask for an early quick review to know if this is the direction we want to follow with this document.
Document at https://docs--9755.org.readthedocs.build/en/9755/guides/hosting-integrations.html
Related #9036
Related https://github.com/readthedocs/meta/issues/71
Related https://github.com/readthedocs/meta/discussions/35
📚 Documentation previews 📚
docs): https://docs--9755.org.readthedocs.build/en/9755/dev): https://dev--9755.org.readthedocs.build/en/9755/