Documentation: indicate that the Read the Docs platform accepts other themes than MkDocs' readthedocs
#3579
Comments
fralau
changed the title
readthedocsreadthedocs
|
They boldly state that they are the best deployment solution for MkDocs projects and support all themes. |
|
There you are: 😄. I would take the statement that they support all themes at face value, hence the MkDocs documentation could reflect that? However, I don't know about the claim of Read the Docs being the best platform for MkDocs, since there are also plenty developers of the GitHub Pages obedience, who even have their favorite invocation directly embedded in mkdocs ( In any case, the authors of MkDocs can give themselves a pat on the shoulder, since a hosting platform is vying for the attention of their community 😇 . |
|
Sorry to hi-jack this thread, but it is kind of related – feel free to mark this as off-topic. @humitos – I'm tagging you, since you liked my last comment and work for @readthedocs. What upsets me is that you advertise powerful search among other things in the above the fold of your MkDocs landing page, as if ReadTheDocs provides this functionality, but the search of all testimonials you list on that page further down is entirely powered by Material for MkDocs – in-browser:
The box in the middle is even more specific:
Additionally, collaboration, as I understand, comes from GitHub. I think you're referring to the deployment previews, which are definitely useful, but your marketing lingo, IMHO, is a little misleading. Please correct me if I'm wrong, but ReadTheDocs makes money from hosting MkDocs and Material for MkDocs projects, but does not support those projects in any way, AFAIK. So, the least ReadTheDocs can do is to not advertise built-in features as their own. If you or somebody else at ReadTheDocs would like to talk about this, feel free to comment or reach out to me privately at martin.donath@squidfunk.com. I can only speak for Material for MkDocs, but 75-80% of MkDocs sites use that theme, so my work is quite impacted. |
|
@squidfunk getting a taste of his own medicine, what a day 😂 Maybe you should look at what you're doing first. You are exactly advertising MkDocs' features as your own while soliciting money. And if you would like to talk about this, you can reach out to me privately in Element/Gitter chat where you had blocked me 😂 |
|
To clarify just in case, @squidfunk does not represent "MkDocs" but does represent "Material for MkDocs". From my side on MkDocs, I don't have a problem with ReadTheDocs |
|
To be fair @oprypin, the docs you mention only state that they support these things, while telling they come from standard Markdown and extensions, and giving links to these extensions. They don't say "our list flavors". |
|
@humitos regarding support for "all themes", are you aware of the themes listed in https://github.com/mkdocs/catalog? I personally think your system is indeed able to handle any theme, but I'm curious to know if you test it against some of these 🙂 |
With the introduction of Read the Docs Addons, (see https://blog.readthedocs.com/addons-flyout-menu-beta/), Read the Docs supports any MkDocs theme (and any documentation tool). Before addons, the integrations where built at theme level and that's why the BTW, Read the Docs Addons is still in beta and we are working towards making it more stable and exposing Read the Docs data via a JavaScript
We plan to do a good refactor of our introductory documentation content starting by the end of March, so this page will be affected by this work. I will pass this feedback to the team working on this 👍🏼 |
This affirmation is clearly subjective 😅 , but yea, we consider ourselves as the best platform to host MkDocs' documentation projects 😉 |
Read the Docs provides a powerful search built with Elasticsearch (https://docs.readthedocs.io/en/stable/server-side-search/index.html) that works on any documentation tool that generates HTML files. Besides, it exposes an API to that backend server which is used by the Search Addons to provide a search as-you-type experience. Example on a MkDocs site with the Material for MkDocs theme (https://docs.pypi.org/):
Example on a Parcel site (https://pycamp.es/):
As you can notice here we have a Read the Docs built-in search as-you-type feature that's documentation tool agnostic and it's not related with the search provided by the documentation tool. We don't attempt to highlight the Material for MkDocs nor MkDocs built-in search here as our feature in any way.
The collaboration comes from Git (not GitHub in particular) + deployment previews, yeah.
I take this feedback and I'm happy to work on improvements here. I'm open to suggestions to improve this particular page, making it clearer for everybody and avoiding confusions. The repository is public, so we can move this conversation into an issue there https://github.com/readthedocs/website or even receive a PR with suggestions.
I personally don't think that Read the Docs is advertising features it doesn't have, and I hope you think the same after my explanation here. Let me know otherwise. We can make changes and adjustments to that page to better reflect what Read the Docs offers.
I wanted to comment here because this was risen in public in this particular issue, but I'm happy to talk and discuss more about this (or even a bigger collaboration with Material for MkDocs as we talked in the past) either in the repository I linked before (where all the Read the Docs team has access to) or privately via email at manuel@readthedocs.com I hope my comment here helps to clarify the situation and to make the required adjustments to that page to avoid confusions. |
|
Wow, I didn't expect to cause a stir, but it's OK 🙂 I will try to throw in my two-bit. First of all, I have respect for the characters involved in the development of MkDocs and its ecosystem. We all take pride in our own contributions, so I understand any person who feels they were not acknowledged for it. Also, I am not surprised that there are, at times, conflicting trends and interests, especially between volunteer and paid actors, and within these those two categories (those tensions are in the essence of Open Source and it's an indication that our community is alive and kicking). I believe that there is nothing that good communication (between humans) couldn't solve. That being said, we are facing a unique challenge, that stems from the genius idea behind MkDocs: it's modularity. For my mermaid2 plugin for MkDocs, when I wrote the How to Contribute section and tried to make a diagram of the ecosystem I realized that there is a structural challenge in our community. Note: I am actually giving the updated diagram; I'm having a compile trouble on ReadTheDocs apparently connected git, and for the life of me I couldn't find the solution. I opened a ticket. I am not claiming that this diagram is particularly scientific or accurate, but it has the merit to indicate that in case something is not working as we expected (some bug or misbehavior) it is not always clear where to open a ticket. If those who work closest with development around MkDocs are sometimes pausing to think, it is not wonder that the community at large feels confused. But this also applies when MkDocs is actually working well, exactlly as we expected. So when all is said and done who's got the merit for this success? My view is that Mkdocs is not a monolithic product but an ecosystem built around a core: it's a loose collection of components and actors, who are all co-dependent and interdependent. All the actors are essential, none of them are expendable, and removing one could compromise the rest. As far as I am concerned, I developed MkDocs-Macros because I knew that if one wanted MkDocs to hold the ground against highly flexible tools such as Hugo, one needed to leverage a powerful templating system like Jinja2 directly in the Markdown pages. That was my goal, so if suddenly MkDocs decided to boast about MkDocs-Macros, I wouldn't mind at all! It would be nice if they put a nice credit my name, but I wouldn't feel offended if they didn't (as long as no one tries to erase me from the face of Earth). But it's true, my income stream doesn't depend on MkDocs, so I can afford to be more selfless than others. Bottom line: I am grateful to all the actors who are arguing here each for their respective contributions, because without MkDocs, Material, PyMDown, Read The Docs, and others -- the projects I am working would never have seen the light, or would have been very different! I would mention Material as a distinguishing factor, because I feel it was the extra "polish" touch that turned MkDocs into a winner. And also because @squidfunk spent a lot of time reflecting and working on how to federate those tools into a consistent pattern, and -- most importantly -- he documented his doctrine, and made it work. That is not, of course, to say that it is the only possible doctrine, or to minimize the other contributions. Indeed, his work would not have been possible without those. We are all mixing and matching the contributions of others, with ours to a point where it's hard to say any longer which is which. As long as the economic interests of everyone are respected and preserved, does it really matter to distinguish who invented what? |
I haven't tried them, but if it works locally it should work on Read the Docs. Are you curious about anyone in particular? I can create an example building on Read the Docs for it. In the meantime I took |
|
Awesome, thanks @humitos! I didn't have any particular theme in mind 🙂 |
|
@humitos – thank you for taking the time to respond. I'm aware that ReadTheDocs has its own search backend that is powered by ElasticSearch. My particular point is that the testimonials you have on the marketing site all use the built-in Material for MkDocs search, which I find kind of misleading when you advertise your powerful search front and center:
I'm not the one to decide which search implementation is better, I for my part leave this decision to the user. |
I can only sign that. In fact, ReadTheDocs and Sphinx were the very reason I started Material for MkDocs when reviewing the documentation landscape in 2015, settling on MkDocs for my first Open Source project that needed documentation besides a plain README. A few months later, the first version of Material for MkDocs was released. I really love being part of such a huge and useful ecosystem, and try very hard to make my part a little bit better every day. |
Thanks for this feedback. I think we can update those testimonials to reflect this in a better way. However, note that those are just examples of projects using MkDocs to build their documentation and host them on Read the Docs. They are not examples of "projects using Read the Docs powered Elasticsearch backend with the search as-you-type frontend" These projects are using other features that Read the Docs provide like versioning and translations, or deployment previous, redirects, automation rules, etc, or just using Read the Docs as their CI and hosting platform. Read the Docs has a bunch of features and each of them can be enabled/disabled so there will be project using search as-you-type and other just using versioning or any other combination. I'm happy to update those testimonials with other MkDocs projects hosted on Read the Docs that are using our addons search as-you-type implementation if that helps here. Probably, the one that I mentioned before, https://docs.pypi.org/, is a good one to include. |
|
I want to take the time to answer this reply by @oprypin:
If our documentation, at any point, raises the impression that we are advertising MkDocs' or any of our upstream dependencies features as our own, we need to fix that as soon as possible. I'm not sure why you picked the lists example, but I will take a look at it and see if we can improve it, denoting even further that list parsing is provided by Python Markdown and Python Markdown Extensions, with Material for MkDocs "only" adding the styling. We try to strive a balance between linking to dependencies and not adding too much links, because we don't want to overwhelm our users with links. IMHO, there is a sweetspot. We always link to the extensions under the configuration section, where we clearly attribute them and also link to their upstream sources. All third-party plugins that we support are linked to their sources + clearly marked as third-party (non built-in plugins). Again, we are very happy to do better, so if you have concrete suggestions, we'll definitely look into them.
I'm not sure if its clever to open this can of worms here. Yes, I blocked you on Gitter, and you precisely know why. I always try to be helpful and nice, and love working with the awesome people that are part of this striving ecosystem. I also support upstream contributors and maintainers financially in the maximum way that I can currently afford, and I will raise those contributions in the future. I want the MkDocs ecosystem to blossom. Otherwise, my work would be quite pointless. However, there's a limit to my interaction if the counterpart is not respectful. Thus, please, please, please, let's just work together constructively and respect each other's opinions, goals, and motivations. |
|
I am glad that these points were somewhat cleared up. From where I stand, it seems that the main takeaway is acknowledgement (particularly, our respective contributions). I think it was well spent time, since we evidently all feell strongly about documentation (document code, write code for documentation and treat our documentation as code) otherwise none of us would have bothered to put some much effort on a documentation tool. 🙂 Back to my initial question:
|
No, you don't get to say "you know what you did" when I didn't do anything. You slammed the door shut when I was only bringing up in a simple way how your most recent addition at the time was in fact not respectful to the ecosystem. Which may be annoying if I bring up multiple of those things but what to do if that's how I see it. Meanwhile my other big point that I was saying to you was that collaboration on ideas and focus on users' usecases is nearly the only thing that can awake my productivity. And that has been really lacking for me (in general, in the background). Instead all I have is this source of hurt that's always there in the distance - "things are not ok". |
|
@oprypin Okay, so if you want to discuss this, we can. If we do this, I feel like it is fair to give the full picture from my perspective, as I can't just let some of the allegations uncommented. On an important note, everything that I will talk about in the coming paragraphs is public and can be found on GitHub or Gitter, so I'm not sharing any information that wasn't already disclosed, except for the reason why I blocked you. I deliberately decided not to include sources to issues or comments in this argument, because I don't want this to turn into a witch hunt. I'm not trying to make you look bad, I'm trying to make you understand how I feel about this. I think you agree that we have quite a history working together. On several of our first encounters before you were on the MkDocs core team and before I started with sponsorware, you criticized my work multiple times in public and dragged things on a personal level. You know, I'm super happy to receive constructive criticism, as I try very hard to make Material for MkDocs one of the best and simplest solutions to write documentation, and I have no problem to agree to disagree, because software is opinionated, but being insulted for not considering something for merging is not fair. If you just had a bad day and would've apologized, no problem, really, we all have, but you did not. I have never, ever, ever insulted you publicly or privately. I have never questioned your competence, au contraire (coming to it). I believe that you do an amazing job. Then I started with the sponsorware program after users motivated me to do it, because of the value that Material for MkDocs brings them. During this time, we were both quite active on Gitter. You repeatedly spoke bad of my work and the sponsorware program in front of other users. I thought: okay, let's discuss it, and so we did. I was very open to your criticism and tried to explain publicly in front of other users that the sponsorware program is the only reason that Material for MkDocs is what it is. This did not happen once, it happened on multiple occasions, and I felt we were getting nowhere. Regardless, I tried to keep my cool and explained my point of view every time. At some point you wanted to join the MkDocs core team, as issues were piling up and MkDocs could use some more helping hands. Putting our differences aside, I publicly vouched for getting you on the core team and assured Tom Christie, the creator of MkDocs, that I believe that this is a great idea. Again, I believe in your work and was putting our differences aside, as I believe that they do not matter. This is all publicly documented, so if somebody wants to read it, just use GitHub search. Then you finally started accepting sponsorships yourself, which I've tried to motivate you on multiple occasions. Remember, we also met once in person. Although you did not answer my last message on Gitter for six months, I started sponsoring you immediately (I'm still your first sponsor) because I believed that we can sort it out. At some point you wrote me a message on Gitter that you realized that some of your actions might have been wrong and that you are sorry. I was happy to hear from you, and also increased my sponsorship that very moment, looking forward to great collaboration. I believed that we could finally work together. But shortly after, you started to criticize my work again, saying that (I believe the wording was) my work on the group plugin is "awfully misguided" (which I think you're referring to). After talking to other people, I came to the conclusion, that given our history, we should limit our communication to the public space, because private communication was not working out for us. This is why I blocked you on Gitter. After that, we had some interactions here and there, some of them constructive, some not. When you called me out again, I always took the time to write a long reply, but never heard back from you. This issue is in fact the first time I hear something back from you. I'm very sorry that this is off-topic again, but I do not want to open a new discussion and give this even more space, because I still hope that it can be sorted out and we can work together while constraining our interaction to the public space. I hope you can understand and accept it. After all, we all want the same thing: empower users to build awesome documentation. |
Point well taken: this issue seems to matter enough to warrant a separate thread of discussion; or (better) a resolutive face-to-face discussion between the two parties, to arrive at an agreed-upon position; and then to communicate it to the others. However, should this direct approach not be desirable at the moment, I would recommend that we close that argument for now, until a better opportunity presents itself. And in the mean time, I suggest we return to the initial question:
|
|
I noticed that mkdocs material has integrated with the new readthedocs addons, but can anyone point me to the guide on how I can customize the position of the flyout badge using the new approach? |
This commit updates the documentation about "Read the Docs": - removes unsupported version control systems; only Git is supported now (see https://about.readthedocs.com/blog/2024/02/drop-support-for-subversion-mercurial-bazaar/) - removes the note mentioning that not all the features are supported with other MkDocs themes since this is not valid anymore Closes mkdocs#3579
@fralau I opened #3683 to update the documentation with the latest changes on Read the Docs. Let me know if it makes sense for you. |
|
@humitos Sure! |
The official MkDocs page, states that the Read The Docs platform accept only the MkDocs
readthedocstheme.Fortunately Read The Docs is more tolerant, though I do not know how much. I can say for sure that it accepts the Material theme, since I am deploying the documentation of MkDocs-Macros on Read theDocs.
Would it be a good idea to change the wording?
Also it might be a good idea to liaise with Read the Docs team to update their own doc, so that they list the MkDocs themes they support?
The text was updated successfully, but these errors were encountered: