#restructuredtext — Public Fediverse posts

I like the prose linter Vale, because it helps me stay closer in compliance with our documentation style guide.

A bug with handling restructuredtext disturbed my work since yesterday.

On systems using pyenv and having imagemagick installed, each Vale run of rst2html triggers the screenshot tool from imagemagick, because Bash instead of Python interprets `import sys`. It blocks my keyboard input until I click once.

See
https://github.com/vale-cli/vale/issues/1137

#technicalwriting #vale #restructuredtext

Out now: linkotron 0.7!

CLI to format links in a shorter format.

🖇️ Format regular links
🔗 Format GHSA links -- thanks @stanfromireland!
🖇️ Add support for Python 3.15-3.16
🔗 Stop testing experimental 3.13t

Maybe one day I'll remember how to write reStructuredText links but now I don't need to:

❯ linkotron example.com --rst
Copied! `example.com <https://example.com>`__

https://github.com/hugovk/linkotron/releases/tag/0.7.0

#Python #release #linkotron #CLI #reStructuredText

Out now: linkotron 0.7!

CLI to format links in a shorter format.

🖇️ Format regular links
🔗 Format GHSA links -- thanks @stanfromireland!
🖇️ Add support for Python 3.15-3.16
🔗 Stop testing experimental 3.13t

Maybe one day I'll remember how to write reStructuredText links but now I don't need to:

❯ linkotron example.com --rst
Copied! `example.com <https://example.com>`__

https://github.com/hugovk/linkotron/releases/tag/0.7.0

#Python #release #linkotron #CLI #reStructuredText

I think I've more or less decided that I want a #reStructuredText to SXML parser in R6RS #Scheme.

I'm going to try to spend 30 minutes a day working on one, and see how I get on.

rST has been a text-based markup of choice for many years (alongside org-mode), and I was always disappointed by the ascendancy of the inferior #Markdown. It deserves an independent reimplementation.

I think I've more or less decided that I want a #reStructuredText to SXML parser in R6RS #Scheme.

I'm going to try to spend 30 minutes a day working on one, and see how I get on.

rST has been a text-based markup of choice for many years (alongside org-mode), and I was always disappointed by the ascendancy of the inferior #Markdown. It deserves an independent reimplementation.

I finally got around to rebuilding my website using #Python #Django and #reStructuredText . It is now allows me to easily write about projects and write blog posts.

One of my biggest and most useful (to me) hobby projects is my language learning tool #xiaolongdictionary . The last couple of days I have written about the tool and its features extensively [1].

I think I will still improve the writing and extend it in the future.

[1]: https://web.xiaolong-hosting.com/projects/project/xiaolong-dictionary

#coding #programming #blog

I finally got around to rebuilding my website using #Python #Django and #reStructuredText . It is now allows me to easily write about projects and write blog posts.

One of my biggest and most useful (to me) hobby projects is my language learning tool #xiaolongdictionary . The last couple of days I have written about the tool and its features extensively [1].

I think I will still improve the writing and extend it in the future.

[1]: https://web.xiaolong-hosting.com/projects/project/xiaolong-dictionary

#coding #programming #blog

#Papirus 's icon for #ReText is annoying me right now. I'll just do something about that.

By the way, is there an accepted logo for #reStructuredText anywhere, other than the LaTeX-like wordmark on Wikipedia?

#Python #YearOfTheLinuxDesktop

#Papirus 's icon for #ReText is annoying me right now. I'll just do something about that.

By the way, is there an accepted logo for #reStructuredText anywhere, other than the LaTeX-like wordmark on Wikipedia?

#Python #YearOfTheLinuxDesktop

In the age of AI generated #markdown humans should start using #reStructuredText documents 🤔

In the age of AI generated #markdown humans should start using #reStructuredText documents 🤔

I just published a Sphinx extension to add colspan and rowspan to .rst tables: https://pypi.org/project/rst-table-span/

#python #docutils #sphinx #rst #reStructuredText

I just published a Sphinx extension to add colspan and rowspan to .rst tables: https://pypi.org/project/rst-table-span/

#python #docutils #sphinx #rst #reStructuredText

@bithive @timpritlove Me too, because it has a specification from the beginning and not a post specification effort as common mark.

However, Markdown is easy to learn and suits use cases that are enough for many users.

#markdown #restructuredtext

@bithive @timpritlove Me too, because it has a specification from the beginning and not a post specification effort as common mark.

However, Markdown is easy to learn and suits use cases that are enough for many users.

#markdown #restructuredtext

#Markdown Is a Disaster: Why and What to Do Instead
https://karl-voit.at/2025/08/17/Markdown-disaster/

Here's my article where I summarize the subtle and no so subtle downsides when you choose Markdown for your information instead of a different markup syntax that doesn't come with all the downsides of #MD.

#publicvoit #orgdown #orgmode #LML #pandoc #rst #restructuredtext #asciidoc #Wikitext #BBCode #Creole #Crossmark #Djot #CommonMark #lockin

#Markdown Is a Disaster: Why and What to Do Instead
https://karl-voit.at/2025/08/17/Markdown-disaster/

Here's my article where I summarize the subtle and no so subtle downsides when you choose Markdown for your information instead of a different markup syntax that doesn't come with all the downsides of #MD.

#publicvoit #orgdown #orgmode #LML #pandoc #rst #restructuredtext #asciidoc #Wikitext #BBCode #Creole #Crossmark #Djot #CommonMark #lockin

I'm trying to add a vertical timeline to my sphinx project. There is an extension that does this? The `sphinx-timeline` is only horizontal.

Ideally I could add internal links in the description or bubble too.

#sphinx #restructuredtext #help

I'm trying to add a vertical timeline to my sphinx project. There is an extension that does this? The `sphinx-timeline` is only horizontal.

Ideally I could add internal links in the description or bubble too.

#sphinx #restructuredtext #help

🚀️ rst2gemtext v0.5.0 released!

I just released a new version of my lib to convert reStructuredText to Gemtext (the Gemini markup language).

➡️ https://github.com/flozz/rst2gemtext/releases/tag/v0.5.0

This version fixes an ImportError with newer versions of docutils and improved the outputed gemtext.

#python #reStructuredText #gemini #OpenSource

🚀️ rst2gemtext v0.5.0 released!

I just released a new version of my lib to convert reStructuredText to Gemtext (the Gemini markup language).

➡️ https://github.com/flozz/rst2gemtext/releases/tag/v0.5.0

This version fixes an ImportError with newer versions of docutils and improved the outputed gemtext.

#python #reStructuredText #gemini #OpenSource

#reStructuredText, which pre-dates #Markdown, has always been superior for my purposes @danielittlewood.

https://www.docutils.org/rst.html

#reStructuredText, which pre-dates #Markdown, has always been superior for my purposes @danielittlewood.

https://www.docutils.org/rst.html

Twisted's coding standard for our #ReStructuredText files is to use what we have termed "semantic newlines". That is to say: every sentence is on its own line. In principle, I like this. It means smaller, more readable diffs, and less pointless churn. In practice, with my #Emacs fill-paragraph muscle memory, it is a *constant* frustrating exercise where I'm tripping over myself and either constantly re-wrapping and then manually un-wrapping, or forgetting to wrap at all.

Twisted's coding standard for our #ReStructuredText files is to use what we have termed "semantic newlines". That is to say: every sentence is on its own line. In principle, I like this. It means smaller, more readable diffs, and less pointless churn. In practice, with my #Emacs fill-paragraph muscle memory, it is a *constant* frustrating exercise where I'm tripping over myself and either constantly re-wrapping and then manually un-wrapping, or forgetting to wrap at all.

Hawkmoth v0.20 is out!

Hawkmoth is a Sphinx extension to import C and C++ documentation comments into Sphinx based documentation.

The main new feature in this release is automatic configuration of the system header search paths. Unfortunately, libclang does not get them right out of the box on most distros, so we have to help it a little.

#Sphinx #Hawkmoth #Documentation #reStructuredText #C

https://github.com/jnikula/hawkmoth

AI в работе технического писателя

Всем привет! Меня зовут Севара Ахтямова и я работаю техническим писателем – аналитиком около 4 лет. В этой статье я расскажу, как AI помог мне справиться с рабочей рутиной — от генерации toctree до отладки сборки Sphinx-документации. Всё это — на реальных задачах. Я постаралась собрать побольше примеров из личного опыта. Надеюсь, не слишком много.

https://habr.com/ru/articles/896998/

#ai #искусственный_интеллект #sphinx #документация #автоматизация #технический_писатель #рабочие_процессы #restructuredtext #chatgpt #sphinx_docs

When writing plain-text files with collaborators, such as…

- #LaTeX, for instance on #Overleaf
- #reStructuredText, for instance for use with Sphinx/for @readthedocs
- #Markdown for many purposes.

…a practice I find very helpful is to:

1. Start every sentence on a new line, and
2. Not hard-wrap within sentences.

This makes it MUCH easier to read ordinary diffs and interpret the addition/removal/reordering of sentences, words, paragraphs, etc.

When writing plain-text files with collaborators, such as…

- #LaTeX, for instance on #Overleaf
- #reStructuredText, for instance for use with Sphinx/for @readthedocs
- #Markdown for many purposes.

…a practice I find very helpful is to:

1. Start every sentence on a new line, and
2. Not hard-wrap within sentences.

This makes it MUCH easier to read ordinary diffs and interpret the addition/removal/reordering of sentences, words, paragraphs, etc.

RestructuredText is more powerful, and full featured than Markdown. Everyone should be using RestructuredText instead of Markdown for their documents and Static Site Generators.

#RestructuredText #Markdown #SSG #WebDev #DevLife

RestructuredText is more powerful, and full featured than Markdown. Everyone should be using RestructuredText instead of Markdown for their documents and Static Site Generators.

#RestructuredText #Markdown #SSG #WebDev #DevLife

🚀️ rst2gemtext v0.4.0 released!

rst2gemtext is a CLI tool and a #Python library to convert #reStructuredText to #Gemtext (the markup language used by #Gemini network).

➡️ https://github.com/flozz/rst2gemtext/releases/tag/v0.4.0

This release contains mostly fixes on lists of link and tables. Supported Python versions have also been updated. 😃️

🚀️ rst2gemtext v0.4.0 released!

rst2gemtext is a CLI tool and a #Python library to convert #reStructuredText to #Gemtext (the markup language used by #Gemini network).

➡️ https://github.com/flozz/rst2gemtext/releases/tag/v0.4.0

This release contains mostly fixes on lists of link and tables. Supported Python versions have also been updated. 😃️

@ax6761 @perl I sympathize. Would that mean you would author #Perl POD but then convert to #reStructuredText for #Python? Because #Pandoc can already do that as of this week:

```
pandoc --from=pod --to=rst
```

@ax6761 @perl I sympathize. Would that mean you would author #Perl POD but then convert to #reStructuredText for #Python? Because #Pandoc can already do that as of this week:

```
pandoc --from=pod --to=rst
```

🆕 #pandoc 3.6 has been released:
• Support for #mdoc as input format
• Improved parsing of #reStructuredText
• #Typst 0.12 support
• Safe handling of `--embed-resources` when combined with `--sandbox`

The default templates for LaTeX, ConTeXt, and Typst have been updated.

https://github.com/jgm/pandoc/releases/tag/3.6

🆕 #pandoc 3.6 has been released:
• Support for #mdoc as input format
• Improved parsing of #reStructuredText
• #Typst 0.12 support
• Safe handling of `--embed-resources` when combined with `--sandbox`

The default templates for LaTeX, ConTeXt, and Typst have been updated.

https://github.com/jgm/pandoc/releases/tag/3.6

Thinking about transitioning my #blogging from #nikola to #mkdocs

Nikola is great but I've always felt like writing in Markdown is an also ran use case, as its native lingua franca is my long time nemesis #restructuredtext (Hate hate HATE! :) ).

mkdocs is built from the ground up to be super simple. Give it a pile of Markdown and it'll generate a site. There's a nice plugin for generating a blog:

https://github.com/squidfunk/mkdocs-material/blob/master/docs/setup/setting-up-a-blog.md

Thinking about transitioning my #blogging from #nikola to #mkdocs

Nikola is great but I've always felt like writing in Markdown is an also ran use case, as its native lingua franca is my long time nemesis #restructuredtext (Hate hate HATE! :) ).

mkdocs is built from the ground up to be super simple. Give it a pile of Markdown and it'll generate a site. There's a nice plugin for generating a blog:

https://github.com/squidfunk/mkdocs-material/blob/master/docs/setup/setting-up-a-blog.md

Sphinx 8.1.0 has just been released 🎉

Sphinx makes it easy to create intelligent and beautiful documentation. ✨

See here the changelog 👇
https://www.sphinx-doc.org/en/master/changes/index.html#release-8-1-0-released-oct-10-2024

#Python #Sphinx #Documentation #Generator #reStructuredText #MyST #Markdown

Sphinx 8.1.0 has just been released 🎉

Sphinx makes it easy to create intelligent and beautiful documentation. ✨

See here the changelog 👇
https://www.sphinx-doc.org/en/master/changes/index.html#release-8-1-0-released-oct-10-2024

#Python #Sphinx #Documentation #Generator #reStructuredText #MyST #Markdown

@kurau

https://getpelican.com/

I like #reStructuredText, so this is the best one for me (but it can do #Markdown these days as well).

#OpenWeb #Blog #SmallWeb

Novedades de @pandoc .
Pandoc es una utilidad para la conversión de formatos de archivo, en esencia, de texto plano, que utiliza una estructura de representación intermedia para poder "compilar" a otros formatos.
Ejemplo, puedes convertir de #ReStructuredText a #MarkDown o #LaTeX.
En su novedad, está el cambio de la dependencia para generar PDF por Weasyprint.
#pandoc

@paulox https://fosstodon.org/@paulox/113140526345298176

Novedades de @pandoc .
Pandoc es una utilidad para la conversión de formatos de archivo, en esencia, de texto plano, que utiliza una estructura de representación intermedia para poder "compilar" a otros formatos.
Ejemplo, puedes convertir de #ReStructuredText a #MarkDown o #LaTeX.
En su novedad, está el cambio de la dependencia para generar PDF por Weasyprint.
#pandoc

@paulox https://fosstodon.org/@paulox/113140526345298176

🚀🖊️ Just released: Sphinx Lint 1.0.0

You can add it to your pre-commit to help find nits in your reStructuredText docs.

https://pypi.org/project/sphinx-lint/

https://github.com/sphinx-contrib/sphinx-lint/releases/tag/v1.0.0

#Python #docs #SphinxLint #Sphinx #lint #reStructuredText #reST #rst #precommit

🚀🖊️ Just released: Sphinx Lint 1.0.0

You can add it to your pre-commit to help find nits in your reStructuredText docs.

https://pypi.org/project/sphinx-lint/

https://github.com/sphinx-contrib/sphinx-lint/releases/tag/v1.0.0

#Python #docs #SphinxLint #Sphinx #lint #reStructuredText #reST #rst #precommit

@pdcawley #Markdown acknowledges its #Textile, #Setext, #reStructuredText, et al influences but prioritizes human readability more: https://daringfireball.net/projects/markdown/syntax#philosophy

@bbatsov Exactly, if you made research on #Python programmers, you would get quite different results (we all use #reStructuredText ).

@pludikovsky When people are in favor of #Markdown, they either do mean the concept of lightweight #markup languages (#LML) in general (yeah!) or they do not really know many other LMLs in comparison.

Furthermore, people voting for MD often do ignore the obvious downsides of that ecosystem because they have already overcome some of them, ignoring the majority of people who still need to learn that LML in future. 😔

#orgdown #orgmode #rst #reStructuredText #AsciiDoc

Are you surprised by those results? It seems that #AsciiDoc and #reStructuredText are (way) less popular than I thought, and that #orgmode is way more popular than I expected.

Of course, we should take those results with a grain of salt, as I assume many of my followers are #Emacs users. 😀

This large scale conversion from #LaTeX to #reStructuredText was achieved thanks to #PanDoc, plus a sprinkling of ah hoc fixers using sed and Python. https://github.com/jgm/pandoc