Re: [Docutils-users] GitHub & CSS Docs

[Guenter M. <mi...@us...>]

On 2019-11-13, Jan 'oglop' Gazda wrote:

> [-- Type: text/plain, Encoding:  --]

> Hello everyone,

> I noticed there are more and more requests in moving the project over to
> GitHub, may I know why are you not considering moving over?

The reasoning is unchanged: don't change a running system unless there is a
compelling reason to do so.

Switching to git as master repository format has advantages that may be
worth the effort (if done right), moving to another host does not seem so.


> Another question is about the documentation.
> I love RST especially due to it's style versatility and I think that
> docutils and Sphinx were the best inventions after python.
> But I suffer from dyslexia and current docs format makes it very difficult
> to read for me.

Can you elaborate? Is it about fonts, sizes or structure?

> It would much better to use Sphinx or some CSS which makes it easier to
> read.

> During my research I noticed several docutils forks around the internet
> (github) doing exactly the same thing I did (fork the docutils and process
> docs with sphinx)

> Here is an example of how does it look in my development flow with PyCharm.

> https://github.com/1oglop1/share/blob/master/README.rst

> Moving towards a better graphical style of docs would enhance the
> readability and prevented a repetitive work.

> Are there any obstacles preventing docutils from moving forward to this?

The idea is to have our documentation as a showcase of "pure" Docutils.

If limited CSS changes could help with readability, we may consider them.
OTOH, the CSS is deliberately "minimalistic".

You may also try to compile the docs with the "html5" writer.

Günter