meteor / meteor-theme-hexo

The framework we use for docs.
https://docs-docs.netlify.com/docs/docs/
MIT License
64 stars 26 forks source link

Re-converge Apollo and Meteor themes. #51

Closed abernix closed 6 years ago

abernix commented 6 years ago

We've had the apollo and master branches going in two similar, though ever-so-slightly different directions for going on a couple years now. As incremental changes have continued on each branch, the maintenance has become quite difficult and most of the themes are on a different commit of the apollo branch (and some on small trunks off of that). Great improvements to the theme are often not propagated out the breadth of doc sites, sometimes causing browsing inconsistencies on split properties.

This PR combines all apollo changes back into the master branch, allowing the operation of two different sites by simply providing a different _config.yml. This was a bit tricky due as many changes were made without considering their effects to other flavors of the theme, and many changes had to be restructured to allow toggle-ability via _config.yml. While there is still room to improve on this re-structuring, I seem to have it providing a consistent experience with the tips of both branches.

This is all thanks to hexo's recently-added support of cascading config files, which also allow us to hoist the more-global configuration variables (such as social_links, permalink, logo, apis, etc.) into site-level configurations, which can be independently updated via (new) apollo-hexo-config and meteor-hexo-config npm packages.

Futhermore, when combined with the updates in this PR, those new npm-based theme configurations, allow this theme to become a npm package, rather than a Git-submodule, and allowing tools such as @renovate-bot (which is configured on many of our repositories) to automatically update the themes (i.e. npms) where they are used through the use of PRs. With proper configuration, those PRs can be automatically merged, though even without that configuration the automatic PR-ing of those repositories, and easy npm update-ability, is already a great improvement over the current process (where the commit is often not bumped when a theme change is made).

Lastly, this PR implements a test theme which is automatically deployed to Netlify in both Apollo and Meteor flavors, in order to validate the changes being committed in a more generic sense. Once confirmed that they look okay, the new npm can be published and the downstream projects will receive automatic PRs at the next scheduled interval (usually within a couple hours).

Edit: that test theme now lives in another repo (https://github.com/meteor/theme-example)

abernix commented 6 years ago

It appears that only one of the Deploy preview badges was added to this PR (I had setup two Netlify deploys, which it allowed me to do), presumably because GitHub's API for reporting on such things is "scoped" based on the name (i.e. deploy/netlify), therefore we're probably encountering a namespace clash.

Upon checking the Deploy logs, two did in-fact deploy, so it's only on the PR that it's not showing up properly:

It's super cool that both of those deploys automatically built! However, it's looking like I'll need to have a single Netlify run build both of them within the same build, a bit unfortunate as I'll have to put an extra level path in place and override that part of the config. Shouldn't be too bad though.

abernix commented 6 years ago

Ok, this took a bit of re-factoring because Hexo took up significant issue with having the "example theme usage app" in a sub-directory of the theme itself (cycles, and all), so the example theme now lives in another repository and is pulled in, and matrixed for each desired configuration (as defined in configsToTest.json, during npm test.

Additionally, the problem with Netlify only putting a single deploy preview on this PR has been resolved with a simple index page which links to the tested configs.

abernix commented 6 years ago

Self-merging, as having gone through almost every detail of these changes (read: conflicts), I think I've covered them all about as meticulously as could be. I'm afraid some small design issues may surface once this gets into the wild, but they will, luckily, be much easier to fix.