#ReadTheDocs

2025-05-20

I am not sprinting at #PyCon #PyConUS but I did work on one of my personal projects today, re-working the CI a bit and putting the docs up on #readTheDocs.

2025-05-06

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.

Zhian N. Kamvarzkamvar@hachyderm.io
2025-04-28

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

2025-04-11

I came across something recently that basically stressed the importance of understanding the tools you use on a daily basis to get the most out of them. It suggested that you need to get familiar with the primary sources of docs as well and not just distilled summaries that hold your hand and give you a generic solution to one particular problem your trying to solve. With that in mind, my reading list lately has been the official docs for #neomutt, #irssi, #i3wm, #opnsense, #tmux. I think this is more important than ever when it's so easy to use an #llm to search for information.

#learning #readthedocs

2025-01-31

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!

2025-01-28

Dose someone have experience with digital #handbooks / #documentation in #Typemill #Readthedocs or #gitbook?
We used simple PDF files for documentation till now but want to switch to a dedicated documentation system.
It should be easy to use for non-techies, customizable, good structure and capable of showing pictures and videos.
Oh and we need to host it by our self.
Thanks in advance.

2024-12-20

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

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

habr.com/ru/companies/document

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

2024-12-13

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 github.com/navit-gps/navit/pul to get the nice preview from #readthedocs
Preview:
navit--1281.org.readthedocs.bu
Any ideas how to make the Doc's even better?
#doc #docs #Documentation #foss

Elod Pal Csirmazcsirmaz@fosstodon.org
2024-12-01

Hi I have a simple #python project on #github. What's the easiest way to convert #docstring s and type hints to something nice, like static #markdown or #html? I've been looking into #mkdocs, #mkdocstring, #sphinx and #readthedocs but they all seem a bit overkill. Or maybe if you know a great tutorial for one of these tools? Thanks!

Kevin Bowen :xfce:kevinbowen@fosstodon.org
2024-11-25

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.😞

2024-11-18

#python #sphinx I added #darkmode to a #readthedocs page and it was a one line change, due to the beautiful work done in the github.com/MrDogeBro/sphinx_rt
extension.

Do your part!

If you would like to know more, you'll have to ask someone else, because I don't know much about how all that works.🤣

2024-11-08

@jarofgreen along with () also consider a workflow for github pages.

The advantage of gh pages is a gh workflow can be used.

Packages using a custom python build backend, is negatively affected by rtd not running off a workflow and instead assuming the build process is vanilla

westbrookwestbrook
2024-10-25

Have you been disappointed by the passage of time and its negative effect on webcomponents.org?

Think that deserve a place on the internet that belies how practical and productive they are in your work?

Wanna help the bring such a thing to life?

Join us on Discord (discord.gg/KzgaSbGc9q) as we drive to do all this and more for the next generation of web components and web components consumers!

2024-10-02

Also looks like I never bothered with `link rel="canonical"` on my OSS doc sites, so the impending #ReadTheDocs behavior change shouldn't actually require any work on my part! ☺️

ETA: I did in fact do a quick search engine check to confirm that the problem canonical links solve (duplicate search engine results for the same actual page) doesn’t seeeeeeem to be a problem for me. So yay?

2024-10-02

Huh, I had somehow totally missed the new shiny #ReadTheDocs 'app' domain!

Got real confused at the directions for enabling the new modular version of their classic “tweak your Sphinx conf on their end during builds” feature set (now known as "addons”) until I took a closer look.

Very fancy and shiny! Also much more like other, generalist CI platforms, which makes sense in hindsight.

🍒🌳 Hartmut Goebelkirschwipfel@nerdculture.de
2024-09-24

I'm seeking experiences in multi-language #documentation, e.g in #Sphinx #SphinxDoc, #MkDocs, …

What system/tool can you recommend? How do you handle contributions in case a person not speaking English (which is the 'main' language) wants to add some section?

The aim is to create docs for #tryton. Thus as a bonus we need/want multi-country docs, too. E.g. for describing country-specific taxing — where we don't need information for France in the English master neither in the German translation, but the German translation needs different parts for Germany, Austria and Switzerland. (And things get worse counting in all the countries speaking English or French.) If you have experiences with this, please share.

#followerpower #PleaseBoost #ReadTheDocs #RTD

Zhian N. Kamvarzkamvar@hachyderm.io
2024-09-05

Like, I see the benefit of working with rye for setting up new projects and working with well-formed ones, but it's surprisingly difficult to use with #ReadTheDocs because it seems like it wants you to always do things its way and gets upset when you don't.

Zhian N. Kamvarzkamvar@hachyderm.io
2024-09-05

Okay, #python people, how does one get #rye to work well with #ReadTheDocs?

I'm having a bear of a time because rye complains any time I try to do `rye init` because pyproject.toml exists, but then it complains when I try `rye sync` that it could not write the production lock file....

I just want a `.venv/` folder so that I can run `pip -m install -r docs/requirements.txt` and the python with my #Mac is 3.9, but the project requires 3.10 at least :blobfoxrage:

Client Info

Server: https://mastodon.social
Version: 2025.04
Repository: https://github.com/cyevgeniy/lmst