#readthedocs — Public Fediverse posts

@martin_ueding TIL you can use #zensical on #readthedocs #rtd https://docs.readthedocs.com/platform/latest/intro/zensical.html

@martin_ueding TIL you can use #zensical on #readthedocs #rtd https://docs.readthedocs.com/platform/latest/intro/zensical.html

@martin_ueding TIL you can use #zensical on #readthedocs #rtd https://docs.readthedocs.com/platform/latest/intro/zensical.html

@martin_ueding TIL you can use #zensical on #readthedocs #rtd https://docs.readthedocs.com/platform/latest/intro/zensical.html

@martin_ueding TIL you can use #zensical on #readthedocs #rtd https://docs.readthedocs.com/platform/latest/intro/zensical.html

I just transferred an open-source project from GitHub to Codeberg 💙.

Thanks to the good documentation at https://docs.codeberg.org/integrations/read-the-docs/, setting up the integration with Read the Docs was straightforward. ✅

#Codeberg #ReadTheDocs #Documentation

I just transferred an open-source project from GitHub to Codeberg 💙.

Thanks to the good documentation at https://docs.codeberg.org/integrations/read-the-docs/, setting up the integration with Read the Docs was straightforward. ✅

#Codeberg #ReadTheDocs #Documentation

Experimentally, it seems like pushing new "build style" semver tags is sufficient to get #ReadTheDocs / #RTD to update its 'stable' pointer. That'll probably do for now?

E.g., I cut Paramiko 5.0.0+rtd1 and pushed it to GitHub but nowhere else (as it is literally 5.0.0 + a change to my RTD config files which do not impact any users or even contributors, really) and I'm seeing a rebuild w/ its SHA 🎉

Still more friction than I remember, but at least it's better than making a whole new release!

Experimentally, it seems like pushing new "build style" semver tags is sufficient to get #ReadTheDocs / #RTD to update its 'stable' pointer. That'll probably do for now?

E.g., I cut Paramiko 5.0.0+rtd1 and pushed it to GitHub but nowhere else (as it is literally 5.0.0 + a change to my RTD config files which do not impact any users or even contributors, really) and I'm seeing a rebuild w/ its SHA 🎉

Still more friction than I remember, but at least it's better than making a whole new release!

Weird, I could /swear/ #ReadTheDocs' 'stable' version used to track branches only, but the docs and changelog imply it's been branches /or tags/ (and critically, /favoring the latter when both exist/) since like 2018? Am I high?

The behavior as-is makes it hard to push #RTD-only or doc-only changes w/o cutting a whole new tag (and of course, cutting a whole new tag w/o releasing any code to PyPI, looks weird).

I.e., I can't just push a minor config tweak to my 5.0 branch to fix an issue with the 'stable' docs.

Somewhat ironically, my own changelog setup still creates links to 'latest' instead of 'stable' 🙃 but 'stable' is the default otherwise…

Weird, I could /swear/ #ReadTheDocs' 'stable' version used to track branches only, but the docs and changelog imply it's been branches /or tags/ (and critically, /favoring the latter when both exist/) since like 2018? Am I high?

The behavior as-is makes it hard to push #RTD-only or doc-only changes w/o cutting a whole new tag (and of course, cutting a whole new tag w/o releasing any code to PyPI, looks weird).

I.e., I can't just push a minor config tweak to my 5.0 branch to fix an issue with the 'stable' docs.

Somewhat ironically, my own changelog setup still creates links to 'latest' instead of 'stable' 🙃 but 'stable' is the default otherwise…

One of the most hidden super-cool (sorry, born in the 70s) features of #tailwindcss is the `group` class. Put it on an outer div, then inside do a `group-hover:crazy colors` thing and be impressed. #readthedocs (at least once fully): https://tailwindcss.com/docs/hover-focus-and-other-states#styling-based-on-parent-state

#readthedocs has max-width 800px ... yeah, my wide screen monitor 🥱

#uidesign at its best!

#readthedocs has max-width 800px ... yeah, my wide screen monitor 🥱

#uidesign at its best!

I was joking about this, but #ReadTheDocs doesn't support Forgejo yet.

So I have to decide if I want well-supported tools or if I want to get off the major commercial platforms.

I was joking about this, but #ReadTheDocs doesn't support Forgejo yet.

So I have to decide if I want well-supported tools or if I want to get off the major commercial platforms.

Linking to some Python package docs? Replace <pkg>.readthefinedocs.io with <pkg>.rtfd.io to save a few precious characters. It's an official redirect https://docs.readthedocs.com/platform/latest/user-defined-redirects.html#shortlink-with-https-slug-rtfd-io #Python #ReadTheDocs

Linking to some Python package docs? Replace <pkg>.readthefinedocs.io with <pkg>.rtfd.io to save a few precious characters. It's an official redirect https://docs.readthedocs.com/platform/latest/user-defined-redirects.html#shortlink-with-https-slug-rtfd-io #Python #ReadTheDocs

Our website is refreshed! Please check out our new website based on #mkdocs with #readthedocs theme:

TheProtocols Documentation

I feel like this is a very common problem amongst #Python libraries. Most use #ReadTheDocs to host documentation, and the default template has no obvious way to include a link back to GitHub that is visible on every page. One can show the source code of a function/class in the API docs / autodoc, but it's not the full repo. I'd prefer everyone to add an external toctree link to the source code, but I haven't seen anybody doing this.

As a result, when I search for a Python library on the web, the first search result is the RTD page, the second one, if I'm lucky, is the #PyPI page, but the source code is nowhere to be found, and I have to go look for it (often by clicking "Edit this page" in the docs, then manually trimming the URL) :/

I feel like this is a very common problem amongst #Python libraries. Most use #ReadTheDocs to host documentation, and the default template has no obvious way to include a link back to GitHub that is visible on every page. One can show the source code of a function/class in the API docs / autodoc, but it's not the full repo. I'd prefer everyone to add an external toctree link to the source code, but I haven't seen anybody doing this.

As a result, when I search for a Python library on the web, the first search result is the RTD page, the second one, if I'm lucky, is the #PyPI page, but the source code is nowhere to be found, and I have to go look for it (often by clicking "Edit this page" in the docs, then manually trimming the URL) :/

🎉 rtd-dev-docs-l10n is published!

🚀 Preview:

https://projects.localizethedocs.org/rtd-dev-docs-l10n

🌐 Crowdin:

https://localizethedocs.crowdin.com/rtd-dev-docs-l10n

🐙 GitHub:

https://github.com/localizethedocs/rtd-dev-docs-l10n

#Crowdin #GitHub #Sphinx #ReadTheDocs

🎉 rtd-user-docs-l10n is published!

🚀 Preview:

https://projects.localizethedocs.org/rtd-user-docs-l10n

🌐 Crowdin:

https://localizethedocs.crowdin.com/rtd-user-docs-l10n

🐙 GitHub:

https://github.com/localizethedocs/rtd-user-docs-l10n

#Crowdin #GitHub #Sphinx #ReadTheDocs

Signed up to #readthedocs for an open source project:

https://inema.readthedocs.io/en/latest/index.html

Process was pretty smooth, e.g. it supports github integration,
but it's optional and the service doesn't try to force it on you via dark patterns.
Even pausing for hours during the signup steps was fine,
i.e. session didn't time out or something.

Thus, appreciated the experience, even more so given the general enshittification happening elsewhere.

Also migrated my `mvdate` package to Codeberg, moved docs to mkdocs and hosted them on readthedocs.org

Need to release to PyPI on the off chance someone might find it useful.

https://codeberg.org/slackline/mvdate/
https://mvdate.readthedocs.io/en/latest/

Again thanks to those who write and maintain the tools and infrastructure that make it all possible

#python #codeberg #readthedocs #git #magit #emacs #gnu #linux

Also migrated my `mvdate` package to Codeberg, moved docs to mkdocs and hosted them on readthedocs.org

Need to release to PyPI on the off chance someone might find it useful.

https://codeberg.org/slackline/mvdate/
https://mvdate.readthedocs.io/en/latest/

Again thanks to those who write and maintain the tools and infrastructure that make it all possible

#python #codeberg #readthedocs #git #magit #emacs #gnu #linux

#TreeTime #Trees #MindMap #Editor #OpenSource #FreeSoftware

In reaction to several turns of recent events, TreeTime is starting to move away from #GitHub to #Codeberg: https://codeberg.org/jkanev/treetime#readme

There will be a transition period in which both repositories will receive updates in parallel.

The installable packages in #Pypi, the webpage on https://tree-time.info, and the documentation in #readthedocs will stay unaffected.

#TreeTime #Trees #MindMap #Editor #OpenSource #FreeSoftware

In reaction to several turns of recent events, TreeTime is starting to move away from #GitHub to #Codeberg: https://codeberg.org/jkanev/treetime#readme

There will be a transition period in which both repositories will receive updates in parallel.

The installable packages in #Pypi, the webpage on https://tree-time.info, and the documentation in #readthedocs will stay unaffected.

#TreeTime #Trees #MindMap #Editor #OpenSource #FreeSoftware

In reaction to several turns of recent events, TreeTime is starting to move away from #GitHub to #Codeberg: https://codeberg.org/jkanev/treetime#readme

There will be a transition period in which both repositories will receive updates in parallel.

The installable packages in #Pypi, the webpage on https://tree-time.info, and the documentation in #readthedocs will stay unaffected.

#TreeTime #Trees #MindMap #Editor #OpenSource #FreeSoftware

In reaction to several turns of recent events, TreeTime is starting to move away from #GitHub to #Codeberg: https://codeberg.org/jkanev/treetime#readme

There will be a transition period in which both repositories will receive updates in parallel.

The installable packages in #Pypi, the webpage on https://tree-time.info, and the documentation in #readthedocs will stay unaffected.

Late last week, I dusted off a project that had been abandoned by one of our drive-by volunteers about three years ago.

I was strugglin' a bit getting the dependency restraints updated and re-familiarizing myself with the repo and publishing configurations. I think that's in good shape now & I can mostly focus on document conversion & layout.

Now that I've got more familiarity with #Sphinx and #pandoc than I did three years ago, I looking forward to making some progress this week.

It's been a long time itch to scratch of mine & now I've got some time & motivation. We shall see....

#Xfce #Documentation #ReadTheDocs

Late last week, I dusted off a project that had been abandoned by one of our drive-by volunteers about three years ago.

I was strugglin' a bit getting the dependency restraints updated and re-familiarizing myself with the repo and publishing configurations. I think that's in good shape now & I can mostly focus on document conversion & layout.

Now that I've got more familiarity with #Sphinx and #pandoc than I did three years ago, I looking forward to making some progress this week.

It's been a long time itch to scratch of mine & now I've got some time & motivation. We shall see....

#Xfce #Documentation #ReadTheDocs

Divine Documentation

Dad was about my age when he said that reading the manual was better than hypothesis driven button pressing. For teenage me, that took too long. Sure, I may have crashed a computer or two but following my gut got me there. Of course my gut isn’t that smart. In the decades preceding, devices had converged on a common pattern language of buttons. Once learned, the standard grammar of action would reliably deliver me to my destination. 

In programming I was similarly aided by the shared patterns across MATLAB, Python, R, Java, Julia, and even HTML. In the end however, dad was right. Reading documentation is the way. Besides showing correct usage, manuals create a new understanding of my problems. I am able to play with tech thanks to the people that took the effort and the care to create good documentation. This is not limited to code and AI. During the startup years, great handbooks clarified accounting, fundraising, and regulations, areas foreign to me.

I love good documentation and I write documentation. Writing good documentation is hard. It is an exercise in deep empathy with my user. Reaching into the future to give them all they need is part of creating good technology. Often the future user is me and I like it when past me is nice to now me. If an expert Socratic interlocutor is like weight training, documentation is a kindly spirit ancestor parting the mist. 

Maybe it’s something about being this age but now I try to impart good documentation practices to my teams. I also do not discourage pressing buttons to see what happens. Inefficient, but discovery is a fun way to spike interest.

Meanwhile, I’m reading a more basic kind of documentation. Writing English. Having resolved to write more, I’m discovering that words are buttons. Poking them gets me to where I want, but not always. Despite writerly ambitions, the basics are lacking. This became apparent recently when I picked up the book Artful Sentences by Virginia Tufte*. It’s two hundred and seventy pages of wonderful sentences dissected to show their mechanics. I was lost by page 5. The book is, temporarily, in my anti-library. 

So, I’m going to the basics, Strunk and White, and William Zinsser. I’m hoping that Writing to Learn (finished) and On Writing Well (in progress) provide sufficient context about reasons to write to make the most of S&W, for the how, then somewhere down the road, savor Tufte. 

* Those dastardly Tuftes are always making me learn some kind of grammar.

#AI #Business #ContinuousLearning #DevLife #Documentation #EmpathyInDesign #KnowledgeSharing #Leadership #LearningInPublic #ManualsMatter #OpenSource #philosophy #Programming #ReadTheDocs #science #SoftwareDevelopment #Startups #StrunkAndWhite #TechWriting #VirginiaTufte #WilliamZinsser #WritingWell

Divine Documentation

Dad was about my age when he said that reading the manual was better than hypothesis driven button pressing. For teenage me, that took too long. Sure, I may have crashed a computer or two but following my gut got me there. Of course my gut isn’t that smart. In the decades preceding, devices had converged on a common pattern language of buttons. Once learned, the standard grammar of action would reliably deliver me to my destination. 

In programming I was similarly aided by the shared patterns across MATLAB, Python, R, Java, Julia, and even HTML. In the end however, dad was right. Reading documentation is the way. Besides showing correct usage, manuals create a new understanding of my problems. I am able to play with tech thanks to the people that took the effort and the care to create good documentation. This is not limited to code and AI. During the startup years, great handbooks clarified accounting, fundraising, and regulations, areas foreign to me.

I love good documentation and I write documentation. Writing good documentation is hard. It is an exercise in deep empathy with my user. Reaching into the future to give them all they need is part of creating good technology. Often the future user is me and I like it when past me is nice to now me. If an expert Socratic interlocutor is like weight training, documentation is a kindly spirit ancestor parting the mist. 

Maybe it’s something about being this age but now I try to impart good documentation practices to my teams. I also do not discourage pressing buttons to see what happens. Inefficient, but discovery is a fun way to spike interest.

Meanwhile, I’m reading a more basic kind of documentation. Writing English. Having resolved to write more, I’m discovering that words are buttons. Poking them gets me to where I want, but not always. Despite writerly ambitions, the basics are lacking. This became apparent recently when I picked up the book Artful Sentences by Virginia Tufte*. It’s two hundred and seventy pages of wonderful sentences dissected to show their mechanics. I was lost by page 5. The book is, temporarily, in my anti-library. 

So, I’m going to the basics, Strunk and White, and William Zinsser. I’m hoping that Writing to Learn (finished) and On Writing Well (in progress) provide sufficient context about reasons to write to make the most of S&W, for the how, then somewhere down the road, savor Tufte. 

* Those dastardly Tuftes are always making me learn some kind of grammar.

#AI #Business #ContinuousLearning #DevLife #Documentation #EmpathyInDesign #KnowledgeSharing #Leadership #LearningInPublic #ManualsMatter #OpenSource #philosophy #Programming #ReadTheDocs #science #SoftwareDevelopment #Startups #StrunkAndWhite #TechWriting #VirginiaTufte #WilliamZinsser #WritingWell

Seeing epic failures provides clarity when you are doing things correctly on your own teams. This last 5 days has been an adventure and the timer is still running. Absolutely avoidable if people would have read documentation. #docs #readthedocs #developers

Seeing epic failures provides clarity when you are doing things correctly on your own teams. This last 5 days has been an adventure and the timer is still running. Absolutely avoidable if people would have read documentation. #docs #readthedocs #developers

Sitting in Day 5 of troubleshooting and attempting to fix an issue in production that could have been avoided if the developers on that team would have read the documentation and shared details to the client to avoid the headache and breaking of critical features needed for normal workflows to work. #readthedocs #documentation #developers

Sitting in Day 5 of troubleshooting and attempting to fix an issue in production that could have been avoided if the developers on that team would have read the documentation and shared details to the client to avoid the headache and breaking of critical features needed for normal workflows to work. #readthedocs #documentation #developers

I have asked #GPT-4.0 to translate a news report from Dutch to German for me because I wanted to inform my family about current debates in the Netherlands. I was surprised that #ChatGPT started a #deepsearch although I had not actively selected this feature. I had vaguely heard about it but never used it before, and I am still wondering what it actually does. I will have to #readthedocs for sure! But has anyone got insights they'd like to share? Deep search sounds a lot like #energywaste to me.

I have asked #GPT-4.0 to translate a news report from Dutch to German for me because I wanted to inform my family about current debates in the Netherlands. I was surprised that #ChatGPT started a #deepsearch although I had not actively selected this feature. I had vaguely heard about it but never used it before, and I am still wondering what it actually does. I will have to #readthedocs for sure! But has anyone got insights they'd like to share? Deep search sounds a lot like #energywaste to me.

Coming from #MkDocs on #ReadTheDocs , I think about migrating our projects user manual to #Asciidoc using #asciidoctor and/or #antora .

But I wonder if there is a service like #readthedocs for #asciidoc based manuals available for #OpenSource or #foss projects.

Important is that those platforms do support @Codeberg (#forgejo aka #gita ) code hosting, instead of Microsoft GitHub.

Coming from #MkDocs on #ReadTheDocs , I think about migrating our projects user manual to #Asciidoc using #asciidoctor and/or #antora .

But I wonder if there is a service like #readthedocs for #asciidoc based manuals available for #OpenSource or #foss projects.

Important is that those platforms do support @Codeberg (#forgejo aka #gita ) code hosting, instead of Microsoft GitHub.

I'm in a situation where an organization has a #ReadTheDocs website registered as `<project>.io` (via #NameCheap). Note that no one in this organization are experts or even practitioners of web publishing. People are realizing that the documentation site is not the best landing page and want to do two things:

1. move the documentation site to `docs.<project>.io`
2. set `<project>.io` to host the landing page built on #GitHub with links out to `<project>.io`

The question is: how the heck does one go about doing this without borking everything? It's clear that external links to the documentation would need to change, but in the meantime, I can see the following:

1. register `docs.<project>.io` and add that to the domains in #ReadTheDocs
2. set `<project>.io` as the CNAME for the GitHub site
3. add JavaScript to the 404 page that detects if the link is attempting to point to the documentation site and provide the correct redirect.

Is there anything else that I'm missing? #Web #DNS

I'm in a situation where an organization has a #ReadTheDocs website registered as `<project>.io` (via #NameCheap). Note that no one in this organization are experts or even practitioners of web publishing. People are realizing that the documentation site is not the best landing page and want to do two things:

1. move the documentation site to `docs.<project>.io`
2. set `<project>.io` to host the landing page built on #GitHub with links out to `<project>.io`

The question is: how the heck does one go about doing this without borking everything? It's clear that external links to the documentation would need to change, but in the meantime, I can see the following:

1. register `docs.<project>.io` and add that to the domains in #ReadTheDocs
2. set `<project>.io` as the CNAME for the GitHub site
3. add JavaScript to the 404 page that detects if the link is attempting to point to the documentation site and provide the correct redirect.

Is there anything else that I'm missing? #Web #DNS

Trying to use a #LLM to find a solution I get instructions to use a piece of code from a framework. Looking into the documentation of this framework it states very clearly that this comes with a huge performance impact for my application. The answer from the LLM did not mention this in any way. #ReadTheDocs!

Trying to use a #LLM to find a solution I get instructions to use a piece of code from a framework. Looking into the documentation of this framework it states very clearly that this comes with a huge performance impact for my application. The answer from the LLM did not mention this in any way. #ReadTheDocs!

«Вымрут» ли печатные пользовательские инструкции?

В эпоху цифровизации техническая документация меняет свои формы и функции. Печатные издания, когда-то считавшиеся основным источником информации, постепенно уступают место онлайн-форматам. Однако остаётся вопрос: есть ли будущее у печатных документов, или их неизбежно ждёт забвение? В этой статье мы разберём преимущества и недостатки обоих форматов, а также рассмотрим современные инструменты, которые помогают создавать качественную и удобную документацию.

https://habr.com/ru/companies/documenterra/articles/868362/

#цифровизация #техническая_документация #печатные_тексты #онлайн #интерактивность #инструменты #notion #readthedocs #gitbook #slack

The #navit wiki has been offline since a long time now. But I finally got around to revisit the migration from #mediawiki to @readthedocs. So far it's not finished, but there is great progress. I already opened the PR at https://github.com/navit-gps/navit/pull/1281 to get the nice preview from #readthedocs
Preview:
https://navit--1281.org.readthedocs.build/en/1281/index.html
Any ideas how to make the Doc's even better?
#doc #docs #Documentation #foss

About 2 or 3 years ago, I had some brave soul step up and volunteer to convert the #Xfce #documentation over to the .rst format to publish to #readthedocs

I was busy at the time; but, I went ahead and set up the initial repos & created the workflow that would allow them to publish the docs on the platform.

IIRC, they lasted several weeks and a handful of docs before they disappeared.

It's definitely not glamorous work.😞

About 2 or 3 years ago, I had some brave soul step up and volunteer to convert the #Xfce #documentation over to the .rst format to publish to #readthedocs

I was busy at the time; but, I went ahead and set up the initial repos & created the workflow that would allow them to publish the docs on the platform.

IIRC, they lasted several weeks and a handful of docs before they disappeared.

It's definitely not glamorous work.😞