Menu
▾
▴
docutils-users
|
From: Wol <ant...@yo...> - 2022-02-21 20:20:22
|
Literal blocks
Literal code blocks (ref) are introduced by ending a paragraph with the
special marker ::. The literal block must be indented (and, like all
paragraphs, separated from the surrounding ones by blank lines):
This is a normal text paragraph. The next paragraph is a code sample::
It is not processed in any way, except
that the indentation is removed.
It can span multiple lines.
This is a normal text paragraph again.
The handling of the :: marker is smart:
-------------------------------------------------------------------------
That's basically copied straight out of the documentation. So why, when
I declare a code block, has it been formatted?
If it's not processed in any way, why have I got colour-highlighting,
and bold text? Dunno what else it'll do ...
Or is trying to use Sphinx to write documentation just an exercise in
frustration? Okay, it has printed it cleanly in a fixed-width font, but
it certainly doesn't appear to have done what the documentation says it
does!
Cheers,
Wol
|
|
From: Wol <ant...@yo...> - 2022-02-21 23:55:17
|
Now this gets really weird ... I've put in a second literal block and what does it do? Lays it out as plain text, EXACTLY AS I WOULD EXPECT! Apart from the background, which I don't really want. But, forgetting all the grief so far, how would YOU recommend me to achieve what I'm actually aiming for, which is plain text laid out in columns? Thing is, a lot of what I'm doing is I'm starting with two columns, and then splitting up the second column in two, that sort of thing ... (I want it to look modern, proportional fonts, etc etc, but while it is a table I DON'T want it to LOOK like it's been laid out as a table...) Cheers, Wol On 21/02/2022 20:20, Wol wrote: > Literal blocks > > Literal code blocks (ref) are introduced by ending a paragraph with the > special marker ::. The literal block must be indented (and, like all > paragraphs, separated from the surrounding ones by blank lines): > > This is a normal text paragraph. The next paragraph is a code sample:: > > It is not processed in any way, except > that the indentation is removed. > > It can span multiple lines. > > This is a normal text paragraph again. > > The handling of the :: marker is smart: > > ------------------------------------------------------------------------- > > That's basically copied straight out of the documentation. So why, when > I declare a code block, has it been formatted? > > If it's not processed in any way, why have I got colour-highlighting, > and bold text? Dunno what else it'll do ... > > Or is trying to use Sphinx to write documentation just an exercise in > frustration? Okay, it has printed it cleanly in a fixed-width font, but > it certainly doesn't appear to have done what the documentation says it > does! > > Cheers, > Wol > > > _______________________________________________ > Docutils-users mailing list > Doc...@li... > https://lists.sourceforge.net/lists/listinfo/docutils-users > > Please use "Reply All" to reply to the list. |
|
From: Adam T. <aat...@ou...> - 2022-02-22 01:19:19
|
It would be very helpful for you to share a link to a repo that contains a minimal reproducer - I've had to guess a few things about your setup here. > But, forgetting all the grief so far, how would YOU recommend me to achieve what I'm actually aiming for, which is plain text laid out in columns? If you're using Sphinx, the .. class:: directive is renamed to .. rst-class::. Does .. rst-class:: borderless work? > I DON'T want it to LOOK like it's been laid out as a table... By this do you just mean you don't want borders to be shown? A |
|
From: Guenter M. <mi...@us...> - 2022-02-22 11:17:50
|
On 2022-02-21, Wol wrote: > Now this gets really weird ... It seems the reason is that you * don't tell us what you use (apparently Sphinx, not Docutils), * ask at a Docutils users list, * want to achieve something where Sphinx works differently from vanilla Docutils (overriding the "class" directive, overriding the interpretation of "literal blocks"). Depending on your task and wider circumstances, you may consider, e.g. * using a simple text format with fixed width fonts and forget about any kind of markup. * use Docutils instead of Sphinx, read some basic documentation and ask for specific problems here, * use Sphinx, read some basic documentation (https://sphinx-doc.org/) and ask for specific problem there. Trying to vent your undestandable frustation somewhere else might improve the responses from people that develop the tools in their spare time. Günter |
|
From: Wol <ant...@yo...> - 2022-02-22 21:12:34
|
On 22/02/2022 01:03, Adam Turner wrote:
> It would be very helpful for you to share a link to a repo that contains
> a minimal reproducer - I've had to guess a few things about your setup here.
>
> > But, forgetting all the grief so far, how would YOU recommend me to
> achieve what I'm actually aiming for, which is plain text laid out in
> columns?
>
> If you're using Sphinx, the |.. class::| directive is renamed to |..
> rst-class::|. Does |.. rst-class:: borderless| work?
>
Running Sphinx v4.3.2
loading pickled environment... done
building [mo]: targets for 0 po files that are out of date
building [html]: targets for 1 source files that are out of date
updating environment: 0 added, 1 changed, 0 removed
reading sources... [100%] SMA/SMA301
/home/anthony/gitstuff/ScarletDME/docs/source/SMA/SMA301.rst:81:
WARNING: Invalid class attribute value for "rst-class" directive:
"borderless
=========== =========================================================
Item-Id - A character string (maximum 48 characters) which
As you can see, it doesn't like it ...
This is what the source file looks like ...
.. rst-class:: borderless
=========== =========================================================
Item-Id - A character string (maximum 48 characters) which
uniquely identifies an item within a file. The item-id
And the output is that the table just disappears ...
>
>> I DON'T want it to LOOK like it's been laid out as a table...
>
> By this do you just mean you don't want borders to be shown?
>
Yup.
(Actually, I'd like to learn how all this works :-) But I need to get
something that works, and then and can try and understand WHY it works :-)
Cheers,
Wol
|
|
From: Adam T. <aat...@ou...> - 2022-02-22 22:05:50
|
> It would be very helpful for you to share a link to a repo that contains > a minimal reproducer - I've had to guess a few things about your setup here. This request stands, it is challenging to help when I don't have all the detail! > As you can see, it doesn't like it ... Testing locally, it is fine. Your excerpt below is missing the blank line between the directive and the table, though. That might be the source of the error. It also depends on what Sphinx theme you're using, as that will have different classes, so borderless may not work. (The directive applies a class to the Docutils tree, which is used as a CSS class in the HTML output -- your CSS file needs to know what to do with .borderless.) From your reply to Günter, the best way to raise an issue for Sphinx is the issue tracker, https://github.com/sphinx-doc/sphinx/issues/new/choose A |
|
From: Wol <ant...@yo...> - 2022-02-22 21:49:12
|
On 22/02/2022 11:17, Guenter Milde via Docutils-users wrote: > On 2022-02-21, Wol wrote: >> Now this gets really weird ... > > It seems the reason is that you > > * don't tell us what you use (apparently Sphinx, not Docutils), > > * ask at a Docutils users list, Sorry. I looked on the Sphinx web site for the support mailing list, and this was it ... if it's not where you go for Sphinx support, then somebody needs to tell the Sphinx webmaster! > > * want to achieve something where Sphinx works differently from vanilla > Docutils (overriding the "class" directive, overriding the interpretation > of "literal blocks"). > > Depending on your task and wider circumstances, you may consider, e.g. > > * using a simple text format with fixed width fonts and forget about > any kind of markup. > > * use Docutils instead of Sphinx, read some basic documentation and ask for > specific problems here, > > * use Sphinx, read some basic documentation (https://sphinx-doc.org/) > and ask for specific problem there. Except that "there" is apparently here ... > > Trying to vent your undestandable frustation somewhere else might improve > the responses from people that develop the tools in their spare time. > Sorry ... Cheers, Wol |
|
From: Jeff M. <jmc...@ga...> - 2022-02-23 14:49:25
|
On 2022-02-22 3:29 p.m., Wol wrote: > > Sorry. I looked on the Sphinx web site for the support mailing list, and > this was it ... if it's not where you go for Sphinx support, then > somebody needs to tell the Sphinx webmaster! For Sphinx support, goto the Sphinx website ( https://www.sphinx-doc.org/en/master/ ) and look on the right-side panel on that opening page for the text "Questions? Suggestions? Join the sphinx-users mailing list on Google Groups" and click that link. Hope that helps, -jeff -- Jeff McKenna GatewayGeo: Developers of MS4W, MapServer Consulting and Training co-founder of FOSS4G http://gatewaygeo.com/ |
×
Want the latest updates on software, tech news, and AI?
Get latest updates about software, tech news, and AI from SourceForge directly in your inbox once a month.
Thanks for helping keep SourceForge clean.
X