#readthedocs

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

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

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

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

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!

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.

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

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

Wanna help the #webComponentsCG bring such a thing to life?

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

#webDev #w3c #readTheDocs #writeTheDocs

#readthedocs #tech #technology #funny #humor #jokes #memes

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.

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

Open Source Sunday: fixing @readthedocs on h11 https://github.com/python-hyper/h11/pull/177 #python #readthedocs #sphinx #opensource #OpenSourceSunday

Grumble grumble #ReadTheDocs. That new banner/toast thing about the being the latest development version. God it's SO BIG. Grumble Grumble.

So any time I try to build a #ReadTheDocs site locally, I keep getting template errors from #Sphinx. Many of the solutions say "just install the theme manually and it will work," but this is not the case for me.

Anybody have any tips?

https://github.com/readthedocs-examples/example-sphinx-basic/issues/7

#python #RTD

@baldur actually, #LLMs ingesting masses of #OpenSource documentation and then emitting polished and credible seeming mashups with spurious and misleading content is **exactly** what we don't need just now, so I hope #ReadTheDocs will change their policy and just block these bloody things altogether.

#GenerativeAI
#StochasticParrots

@awoodsnet It’s hosted on #ReadTheDocs, using their docs template and Sphinx to generate them.

https://readthedocs.org

The README in my docs folder goes into more detail: https://github.com/ramsey/uuid/tree/4.x/docs

I have created a Read The Docs site for Mecrisp Ice, which is a family of 16, 32 and 64 bit soft core Forth processors written in Verilog and based on the J1 stack machine.

https://mecrisp-ice.readthedocs.io

@Mecrisp #mecrisp #fpga #forth #j1 #stackmachine #readthedocs

@narthur @sloanlance Thanks, that's a fantastic document on pipx that I'd never seen before. It actually explains so well by comparison.
#readthedocs #python #cli

@scy #Podman uses Sphinx but go-md2man is supposed to work as well, they also do some additional preprocessing for #ReadTheDocs if that's desired:
https://github.com/containers/podman/blob/main/docs/source/markdown/options/README.md

But I second "what's wrong with #Pandoc"? Having written roff manually and small custom Pandoc filters and templates but never used Pandoc for roff, I'd be very intrigued to know more (and maybe fix things).

Currently, I'm trying to beat my #ReadTheDocs configs into shape for their impending “you /really/ gotta have a config file on disk now” change (https://blog.readthedocs.com/migrate-configuration-v2/)

Really hoping I can thread the needle re: my www/docs split for the Big Three projects. Relies on the "experimental" form field for saying which /specific/ .readthedocs.yaml to honor. (Also requires duplicating my .readthedocs.yaml twice, but, whatever.)

Release 2.0 of the #python package #pyam_iamc for #dataviz and #scenario analysis of #IntegratedAssessment, #EnergySystems & #MacroEnergy models.

Code #OpenSource on #GitHub, docs & tutorials hosted on #ReadTheDocs, discussion fora via groups.io and #Slack.

The new release removes support for #python earlier than 3.10 for easier maintenance and streamlined development going forward...

Check out the release details at https://github.com/IAMconsortium/pyam/releases/tag/v2.0.0

One headache in modeling & scenario analysis are inconsistent country names across different data sources.
So we developed an open-source #Python package to harmonize names in the #IntegratedAssessment & #EnergySystems communities...

The country names are based on ISO3166-1 standards, and the package has a few utility features to streamline modeling & analysis.

#ReadTheDocs at https://nomenclature-iamc.readthedocs.io/en/stable/api/countries.html, or visit the #GitHub repo at https://github.com/iamconsortium/nomenclature

Let's try this: Dear #lazyweb / #lazyfedi, what is the current go-to if I have to/want to write application #documentation for #endusers?
It is a #rust application, that does contain a lot of #rustdoc already, but that is very specific to the code, like api/developers doc. It is not end user stuff.

So, what to do? Own branch and something in it, that then gets rendered on a Github-or-similar page? A .md file used with #mkdocs? Using #readthedocs and their #sphinx based setup (also their examples are pretty python related). Somehting else?

I would like to stay as near to the code as I can. *Ideally* it would be rustdoc comments, but that can't be, as that is used for the developers doc already. "Just" a file besides, maybe in doc/ sounds better than whole new branch? Also, would be nice if I do NOT have to learn a complete new markup language.

Any #suggestions?

To review the (draft) update of national #SSP projections for #GDP and #population, you can...

1. View the data via our interactive #ScenarioExplorer hosted by the #IIASA #ScenarioServices team
2. Download the full dataset as xlsx
3. Access the data via our #Python or #Rstats API

And with our #opensource package #pyam_iamc, it's as easy as the snippet below...
... to get something that's just like a #pandas #DataFrame - but better!

#ReadTheDocs at https://pyam-iamc.readthedocs.io