[Docutils-users] Customising style sheets for rst2html - confusing documentation

[Chris G]

I want to do some minor tuning to the default html4css1.css so I
looked at the documentation.

I started from:-

http://docutils.sourceforge.net/docs/howto/html-stylesheets.html

There's a typo for a start (or at least it is for my installation),
"rst2html.py --help" should be "rst2html --help". However that's
fairly trivial.

Reading the above web page I *assume* I have to specify my
"my-docutils.css" on the command line when I run rst2html and then my
my-docutils.css imports the default html4css1.css but this isn't
actually explicit.

Then going on to how to specify a custom CSS file the help returned by
"rst2html --help" is a little confusing:-

--stylesheet=<URL> Specify a stylesheet URL, used verbatim. Overrides
--stylesheet-path.
--stylesheet-path=<file>
Specify a stylesheet file, relative to the current
working directory. The path is adjusted relative to
the output HTML file. Overrides --stylesheet.
Default: "/usr/lib/python2.5/site-
packages/docutils/writers/html4css1/html4css1.css"

According to the above both --stylesheet and --stylesheet-path
override each other.

More importantly I assume that "The path is adjusted relative to
the output HTML file." means that I can specify a CSS file in the same
directory as the .rst document as just "my-docutils.css" and it will
be found, is this correct?


Sorry if this sounds a bit negative! It's not intended that way, I
really, really like Docutils and I'm basing nearly all my HTML on
reStructured Text now.

[David Goodger]

Post by Chris G
I want to do some minor tuning to the default html4css1.css so I
looked at the documentation.
I started from:-
http://docutils.sourceforge.net/docs/howto/html-stylesheets.html
There's a typo for a start (or at least it is for my installation),
"rst2html.py --help" should be "rst2html --help". However that's
fairly trivial.

That's specific to your distro. The standard is rst2html.py.

Post by Chris G
Reading the above web page I *assume* I have to specify my
"my-docutils.css" on the command line when I run rst2html and then my
my-docutils.css imports the default html4css1.css but this isn't
actually explicit.

Patches are welcome, including suggested changes to documentation. At
least file a bug report. This message will be forgotten eventually.

Post by Chris G
Then going on to how to specify a custom CSS file the help returned by
"rst2html --help" is a little confusing:-
--stylesheet=<URL> Specify a stylesheet URL, used verbatim. Overrides
--stylesheet-path.
--stylesheet-path=<file>
Specify a stylesheet file, relative to the current
working directory. The path is adjusted relative to
the output HTML file. Overrides --stylesheet.
Default: "/usr/lib/python2.5/site-
packages/docutils/writers/html4css1/html4css1.css"
According to the above both --stylesheet and --stylesheet-path
override each other.

Whichever is used last, wins.

Post by Chris G
More importantly I assume that "The path is adjusted relative to
the output HTML file." means that I can specify a CSS file in the same
directory as the .rst document as just "my-docutils.css" and it will
be found, is this correct?

Assuming your output .html file is in the same directory, yes. The
path to the output file is the important thing here. Try it and see.

Post by Chris G
Sorry if this sounds a bit negative! It's not intended that way, I
really, really like Docutils and I'm basing nearly all my HTML on
reStructured Text now.

That's cool. BTW, there's no space -- it's "reStructuredText", one word.

[Chris G]

Post by David Goodger

Post by Chris G
I want to do some minor tuning to the default html4css1.css so I
looked at the documentation.
I started from:-
http://docutils.sourceforge.net/docs/howto/html-stylesheets.html
There's a typo for a start (or at least it is for my installation),
"rst2html.py --help" should be "rst2html --help". However that's
fairly trivial.

That's specific to your distro. The standard is rst2html.py.

OK, I did wonder where it came from. It seems like a change for
change's sake though!

Post by David Goodger

Post by Chris G
Reading the above web page I *assume* I have to specify my
"my-docutils.css" on the command line when I run rst2html and then my
my-docutils.css imports the default html4css1.css but this isn't
actually explicit.

Patches are welcome, including suggested changes to documentation. At
least file a bug report. This message will be forgotten eventually.

Post by Chris G
Then going on to how to specify a custom CSS file the help returned by
"rst2html --help" is a little confusing:-
--stylesheet=<URL> Specify a stylesheet URL, used verbatim. Overrides
--stylesheet-path.
--stylesheet-path=<file>
Specify a stylesheet file, relative to the current
working directory. The path is adjusted relative to
the output HTML file. Overrides --stylesheet.
Default: "/usr/lib/python2.5/site-
packages/docutils/writers/html4css1/html4css1.css"
According to the above both --stylesheet and --stylesheet-path
override each other.

Whichever is used last, wins.

OK, that makes sense.

Post by David Goodger

Post by Chris G
More importantly I assume that "The path is adjusted relative to
the output HTML file." means that I can specify a CSS file in the same
directory as the .rst document as just "my-docutils.css" and it will
be found, is this correct?

Assuming your output .html file is in the same directory, yes. The
path to the output file is the important thing here. Try it and see.

OK, thanks.

Post by David Goodger

Post by Chris G
Sorry if this sounds a bit negative! It's not intended that way, I
really, really like Docutils and I'm basing nearly all my HTML on
reStructured Text now.

That's cool. BTW, there's no space -- it's "reStructuredText", one word.

Not quite sure why I bothered replying to this, except to say thanks.
:-)