> > > > Just one thought maybe we can enforce the process to achieve docs, maybe > via pre-commit hooks/updating the `breeze release-management publish-docs` > command. So that anytime there is something new published we also check the > docs to achieve
. > Yep. That would be nice to archive the docs as regular publishing process so we do not have to add a new regular process. It would also be faster and incremental. I think there would be one downside with this approach if we move newer > docs out to S3, suppose there are CSS changes done on the theme, we have to > regenerate the HTML for all providers and airflow and their versions anyway > and upload them to S3. TBH, I'm not sure how frequently these changes > occur. WDYT? > There are few cases where I remember things like this happened over the last few year and we need some way to handle such changes * something that happens "regularly" is adding and removing the banner for Airflow Summit - but that was done I think in a single file/place. * we switched from Google Analytics to Matomo for tracking our audience due to ASF Privacy rules and that required to bulk-replace all the embedded analytics code on all pages * we changed (again following board of the ASF kindly asking us to to so) - updated "Installation" pages for all versions to include "source" downloads from "downloads.apache.org" * we can have other, similar requests, policies, requirements, that might "force us" to do it - but also at some point we might want to, say, modernise the look and feel, so it would be great to have a way to do it On the other hand - this all has been done via smart python scripting modifying the generated code, rather than generating it from scratch - and it was far more easier and safer than trying to regenerate code from some old version of provider for example - when the structure/scripts for that old version might be already a bit defunct. The good side of HTML is that this is all text-based and we can write simple scripts to post-process them for such cases - and this is likely fine to keep it this way - we just need to know that we might run such scripts in two places. But if we **could** regenerate old docs reliably using new process, that would be great (but note it would require checking out old tags for all the versions of docs from our "airflow" git history - each version of Airflow/Helm/Provider documentation is generated from specific tag in historical version of the .rst documentation and it requires the software /scripts that were working then to still work (and this might prove to be tricky years from now). > > One downside, of replicating the sidebar and breadcrumb logic is that we > are violating the DRY principle, but I was eventually hoping that we make > Hugo's way to visualize the website primary and can depreciate the > `sphinx_airflow_theme` altogether. What do you all think? > > Oh.. that would be awesome. Removing the "sphinx_airflow_theme" and the way it gets built, developed, deployed and what should be and should not be part of it is the single biggest improvement in the "process" of developing changes to the docs layout/structure/css. It has never been clear to me what goes where and what I should do when I want to do something more complex than adding a page. I still don't know what goes where and why. I always reverse engineer it, and even if I find out, I can't remember it a week later. It's just super non-intuitive split and dependency to RTD theme - having the dependency to the RTD theme is still holding us back and makes it complex to migrate to Sphinx 7. It would be great if we could get rid of both actually (though I have no idea how easy it would be :)) > Thanks, > Utkarsh Sharma >
