search

orchidhq / Orchid

Build and deploy beautiful documentation sites that grow with you
https://orchid.run
GNU General Public License v3.0
513 stars 53 forks source link

A default Maven config prints lots of deprecation warnings #344

Closed mikehearn closed 4 years ago

mikehearn commented 4 years ago

Thanks for the really nice tool!

I followed the instructions to try Orchid out via Maven, and was surprised to discover it by default asks me to do lots of changes I don't know how to do to migrate to new stuff. Shouldn't a fresh site not use deprecated things out of the box? e.g.

[WARN] JavadocGenerator: 
[WARN]     - 
            This SourceDoc generator is being deprecated in favor of a new, more unified, 
            and more modular code-documentation plugin, OrchidSourceDoc. The new system 
            can be enabled now with the `--experimentalSourceDoc` CLI flag, and the legacy 
            generators will be removed in the next major version.

I don't know how to set that flag using Maven and it's not clear why I should care about this?

Likewise:

[WARN] EditorialTheme: 
[WARN]     - Editorial Theme configuration of search has been deprecated, and you should migrate to the `orchidSearch` or `algoliaDocsearch` meta-component config instead. Add `legacySearch: false` to your theme config to hide this warning and prevent the theme from adding these search scripts automatically.

OK but ... isn't this the theme used in the tutorials? This message doesn't even look meant for me, it looks like you talking to yourself :)

cjbrooks12 commented 4 years ago

Yeah, I'm still trying to figure out the best way to go about this. I released breaking changes in the past which broke some users' sites unexpectedly, so this latest major release I have tried this "feature flag" approach to provide a smoother transition path. Definitely not ideal, but they are just warnings and you can safely ignore them when just starting out.

The messages are intended for users who are upgrading existing sites from a previous version because it can be hard for users to know about new/breaking changes if they are only mentioned in the release notes (which may not be read thoroughly). But you're right, it's probably best to hide these warnings from new installations to avoid confusion.