I am fairly confident this will be rejected. Theme choice is subjective and the maintainer was particular about selecting the theme that is currently used.

I honestly proposed what I think is an improvement for the project, not a PR to meet someone's aesthetic taste. From the tests I have carried out, the theme I proposed objectively increases the accessibility of the documentation. In my opinion, the user experience also benefits, and this could just be my opinion if it weren't for the fact that many other projects have adopted "Material for MkDocs" as a theme for their documentation.

@pauloxnet I understand why you've issued this pull request, and I'm very familiar with MkDocs Material. As a matter of fact, I'm sponsored by them, I've contributed to their project, they heavily rely on Pymdown Extensions which I am the author of, and I use their theme in all of my projects. So yes, I am familiar with the project, the features, the accessibility, etc.

As a member of the Python Markdown team, not the lead maintainer, I was just being honest about what I think the outcome was going to be. If I am proven wrong, then so be it. I am not the one who will make the final decision on this.

@facelessuser thanks for the explanation.

But if I'm not alone in thinking that Material for Mkdocs would lead to improved documentation for every users, why should PR surely be rejected? Isn't this a community project?

A community project doesn't mean that every idea from the community is accepted. Personally, I would have brought this up as a discussion first before issuing a PR, but the PR has already been created. I am not the one who will ultimately make the decision, so I'll just leave it at that. If I'm wrong, I'm wrong.

ok thanks for explaining the point of view so well from a team member. I hope this PR is evaluated objectively and based on what is best for users.

A more productive conversation would probably be: what specific features do you feel are missing from the current documentation? What are the bare minimum of accessibility features you feel a site should have?

This PR was created with no explanation as to why you felt the project needed to migrate to MkDocs Material. If I were the maintainer, I would have immediately rejected such a pull just based on the fact the theme was changed with no explanation as to why. Only after my statement did you mention:

From the tests I have carried out, the theme I proposed objectively increases the accessibility of the documentation.

What specific tests? Where did it specifically excel?

It may be that this project is open to implementing some accessibility features to improve documentation and still retain its general, chosen style, or maybe it is fine with just swapping the theme. I don't usually involve myself in documentation decisions with this project, so I'm indifferent to the direction that is chosen. I will state that even if I like the Material theme, I don't feel that any project that uses MkDocs should be forced to use Material, regardless of the reason.

A more productive conversation would probably be ...

Likewise, a more welcoming response to a new project improvement proposal might have been: "Thanks for this new PR" and not "I am fairly confident this will be rejected".

This PR was created with no explanation as to why you felt the project needed to migrate to MkDocs Material.

I actually explained the context in issue #1412, before opening this PR, as is common in all the other Open Source projects I collaborate on, almost all in the Python ecosystem.

If I were the maintainer, I would have immediately rejected such a pull ...

Just because you didn't read the related issue?

... I don't feel that any project that uses MkDocs should be forced to use Material, regardless of the reason.

It doesn't seem to me that anyone is forcing anyone to use anything and I still haven't understood why you perceived my PR as such.

As a user of this project, I often found myself using the documentation and found it outdated and not very accessible, and I wrote this in issue #1412.

As a volunteer contributor to the project, I proposed with this PR to replace the old theme with "Material for MkDocs", since it is more modern and more accessible, solving the above issue.

Regarding the details features and accessibility of MkDocs, I put a link in the issue description when I opened it.

P.S. I added the link to issue #1412 1412 in the description because the reference in the branch name didn't seem clear enough.

I actually explained the context in issue #1412, before opening this PR, as is common in all the other Open Source projects I collaborate on, almost all in the Python ecosystem.

You did not link these issues together until just recently. I did not see the other issue. And if I did, since they were named the same thing, it is certainly possible I dismissed it thinking it was this PR as well. If I did so, then that is my mistake.

With that said, a PR with no link and no reasoning doing something as drastic as changing the entire theme of the documentation that a maintainer spent time to create is likely to be rejected. I was honest and straightforward. Even with your argument of "accessibility", the argument is a bit weak to expect someone to completely change their documentation themes. In retrospect, I could have additionally asked why you think we need to change the theme, but there was no maliciousness in my response even if it was taken that way. I am still uncertain as to what specifically you think the current documentation lacks.

Regarding the details features and accessibility of MkDocs, I put a link in the issue description when I opened it.

Yes, you put a link to all of Material's documentation. Not every feature in Material is needed for every documentation site. Like I said, a more productive conversation would have been to bring up specific features that you felt were lacking from the documentation and an explanation as to why you felt so strongly about them. I am still doubtful this will be accepted, but I will leave this decision up to @waylan.

I actually explained the context in issue #1412, before opening this PR, as is common in all the other Open Source projects I collaborate on, almost all in the Python ecosystem.

You did not link these issues together until just recently.

In almost all the projects where I contribute it is sufficient to name the PR branch with the same issue number, which forces you to always open an issue first before proposing code, as you thought I had done.

Since you missed the issue, I understand that this is not a convention followed in this project and at that point, I added here an explicit link back to the issue.

... a PR ... doing something as drastic as changing the entire theme of the documentation that a maintainer spent time to create is likely to be rejected.

I think I understand the underlying problem here.

I was honest and straightforward.

I would say, not welcoming, but I think those are points of view.

Even with your argument of "accessibility", the argument is a bit weak to expect someone to completely change their documentation themes.

In my issue I not only talked about "accessibility", but also about modernizing the documentation.

At this point, I will add further details in the original issue so as not to lose it in this discussion.

I would say, not welcoming, but I think those are points of view.

Fair enough. I admit that I can be more terse with issues that have no explanations (or in this case what I "perceived" as no explanation). Regardless of the reasons, I think it is a fair argument that I could have softened my original response.

In my issue I not only talked about "accessibility", but also about modernizing the documentation.

I am aware of the "modernizing" statement as well, and I feel that is a far more subjective argument to make as not everyone may like what is considered "modern". I think you may make far more ground with specific accessibilty arguments, but I am doubtful that will cause the project to change the theme, but it could lead to improvements in the documentation.

I have not read through this discussion in full. However, I am very much opposed to using the Material theme. To be clear, I am not opposed to considering another theme if it provides value.

So why am I opposed to the material theme? With apologies to the developers, I hate the look of the theme. Every site I view that uses the theme I can never figure out what is what. It is completely nonsensical to me. I'm not sure if it is a layout or styling problem, but I get frustrated every time.

That said, I think that in many ways the material theme is a great theme. It has a great feature set and some great developers. But if I can't understand the content because if its styling, then none of the other things matter. I have never shared this opinion publicly before because it is very subjective. And I don't want to get into debates about subjective things. Everyone is entitled to their opinion.

Therefore, I am closing this PR. However, if anyone would like to see an improved theme for our documentation, then feel free to open an issue (rather than a PR) to discuss the features that such a theme needs to support. However, please lets keep the discussion on-topic and avoid subjective discussions about styling. If such a discussion can lead to a consensus on a preferred feature set for a theme, then we can explore how to achieve that.