Add a nagging message when the "mkdocs" executable is detected

[oprypin]

• (Background: Details on forking and renaming the project (it's feasible!) #6)

Add a nagging message when the "mkdocs" executable is detected

Plugin authors can join in on this message by simply calling our special module.
(Other than that, there's no way for us to cause it to be imported. So, without any participating plugins nothing happens.)

---

This is my main plan regarding how we can expand adoption of this project. Every plugin that joins us will make us stronger.

We should invite plugins to:

• Depend on properdocs AND mkdocs <=1.6.1 to limit any future shenanigans of mkdocs. The dependency might be a waste but it's almost guaranteed that something will pull it in anyway.

• Add our warning to their MkDocs plugin in the following way:

  import properdocs.replacement_warning
  
  properdocs.replacement_warning.setup()

[oprypin]

I also think I'd like to make the first release of ProperDocs without this nag message but then soon follow it up with a release that has the nag message.

UPDATE: the nag message actually doesn't kick in by itself, so I retract this. Just publish it with the module already available.

[oprypin]

This modified version can be tried out by installing pip install git+https://github.com/properdocs/properdocs.git@refs/pull/21/head

Try running through properdocs executable and running through mkdocs executable.
Try adding the import to your plugin.

[Andre601]

I'm a bit confused on the actual context of when this would be shown.

When a user runs mkdocs while properdocs is installed? When they install a theme/plugin supporting properdocs but use it on mkdocs?

It's hard to think of a message without knowing the cases this would actually be shown in.

[oprypin]

When they install a theme/plugin supporting properdocs but use it on mkdocs?

Yes, but: all mkdocs plugins work out of the box.
We will only ask plugins to add this import so the message can be shown. We will not ask them to drop mkdocs support or to change anything else

[Andre601]

In that case, my idea:

WARNING: MkDocs may break support for your used plugins in the future!

The MkDocs Owner is working on a v2 version which breaks support for current plugins in MkDocs v1.
No info is provided that suggests any backwards compatability being added, nor that plugins will even be supported at all. Further is there no info on whether or not the v2 will be installable through "mkdocs" or a new project name, making this effectively a gamble on if and when the change may happen.

To avoid this, switch to ProperDocs, a continuation of MkDocs v1 with complete theme and Plugin support from MkDocs!

To switch, replace the "mkdocs" dependency with "properdocs" (example: `pip install mkdocs` -> `pip install properdocs`) and most importantly update any command line invocations of "mkdocs" too.
Theme and plugin names should remain unchanged, if they contain "mkdocs". They will be supported.

Doing this will also disable this warning.

For further info, visit https://github.com/ProperDocs

(This warning was initiated by one of the plugins that you depend on.)

[EddyLuten]

I just want to add the message mkdocs-material has added on plugin init. Rather than a big blurb in the console, why don't we do something similar and create a page on properdocs.org with the full rationale and keep the console message to a few highlighted, important bullet points?

I think a wall of text is more easily ignored than a succinct listing of real pain points.

[oprypin]

Sure a page is better. I welcome help regarding what to put to the page and what to keep in the console.

Note that I'll be suppressing the message from material (needs to be done anyway because it does not know that this is no longer mkdocs)

[oprypin]

Works and looks nice even on Windows 👌

[Andre601]

just don't forget to update the discussion link 😅

[oprypin]

Thanks. Uh yes.. I remembered about that one too late, should've updated already in this PR

[oprypin]

Thanks @Andre601 for collaboration on the message. I should've added you somehow to the commit

[Andre601]

I personally don't care that much about such things.

[samrocketman]

Warning fatigue is a reason not to do this. I would like to not have warnings like this pop up in general. ProperDocs is asserting itself in a bad way where instead the project should grow and differentiate itself with improvements.

Expand adoption through good ideas, features, and support. Right now the only difference is one project is throwing a warning. A warning end users can't do anything about if it starts showing up in their dependency trees.

[oprypin]

Hi. I felt that this was a race against time.
Users are in active danger of "upgrading" to "mkdocs 2.0" one day.

mkdocs-material already shows a warning that is not actionable.
Whereas this warning is in fact actionable, with a direct description of how to fix it once and for all.

I am working on bug fixes, and anyone is welcome to do so as well (unlike previously).

So there's your differentiation.

[DevTwilight]

i agree with @oprypin

[samrocketman]

Okay, that's fair; I at least wanted to share my opinion. I appreciate your efforts as I am fully invested in mkdocs 1. I have an offline live editor which supports me automatically refactoring my content (shameless plug mkocs-live-wysiwyg-plugin which is in my GitHub and only supports mkdocs 1).

"Users who can't control the warnings" in this case would be those using my editor. I am fully invested in backstage which is currently mkdocs only.

I suggest you open a ticket with backstage. Their user base is in the 10s of thousands. Ask them to support properdocs so that I don't have to see warnings :-)