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

Just added a #ManPage to JourNote as well. First time writing one in #ReStructuredText; I'm pleasantly impressed with the results. It's more convenient than POD for the purpose, much as I like the older format.

@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

🌗 Emacs 擴充入門：以 reStructuredText 為例
➤ 從 Spacemacs/Doom Emacs 到客製化配置的橋樑
✤ https://blog.tjll.net/a-beginners-guide-to-extending-emacs/
本文提供一份 Emacs 擴充的入門指南，特別針對沒有 Emacs Lisp 背景的使用者。作者藉由自身使用 reStructuredText 撰寫文件時，需要自動完成文件內參照連結的經驗，逐步引導讀者瞭解 Emacs 的可擴充性和自省性。文章詳細介紹瞭如何透過理解 Emacs 的完成系統、鉤子（hooks）以及 Lisp 語法，來開發自訂功能，最終解決在大量文件中查找和選取參照標題的需求，並鼓勵讀者勇於探索 Emacs 的客製化潛力。
+ 這篇文章對於想深入瞭解 Emacs 但又被 Lisp 語法嚇到的人來說，真是及時雨！作者用了一個很貼切的案例，解釋了背後的原理。
+ 非常棒的教學！我一直以為 Emacs 的客製化很難，看完這篇才發現
#Emacs #Lisp #reStructuredText #文件撰寫 #自動完成

why is #reStructuredText link syntax such a fucking mess

#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

🚀️ 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​의 단점 중 하나는 속칭 위키링크(wikilink) 문법이 없다는 것이다. [[page]] 대신 :doc:`title <page>`로 적어야 한다. (:ref:`title`도 된다고 한다.) 많이 쓰면 익숙해지긴 하겠지만 일단은 [[page]]로 적어 놓고 나중에 고칠 거 같다. 장점도 물론 있다. 하지만 위키가 아니라 하이퍼 링크로 인식하게 될 것이다. 위키라는 개념은 이러한 문법 하나에서 시작한 것일 수도 있을 것 같다.

https://stackoverflow.com/questions/37553750/how-can-i-link-reference-another-rest-file-in-the-documentation

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.

문서 표준을 정해야 한다면 #reStructuredText​가 가장 유력하겠지만, 현실은 쓰기 편한 #Markdown​이 대세이다. reST가 Markdown에 비해 쓰기 복잡하긴 하다. 특히 헤더 줄긋기가 귀찮다, 순서도 외워야 하고. 근데 Markdown에 기능 자꾸 추가하느니 처음부터 reST 쓰는 게 낫지 않을까 싶기도 하다.

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

Returning to writing documentation with #reStructuredText and #sphinx after many years of using only #markdown -- what a way to spend a beautiful spring day 😵

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.

@nantucketebooks

Why? What does #Shanthy has which for example #reStructuredText or #AsciiDoc don’t (not mentioning some dialect of #Markdown)?

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. 😃️

@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
```