I am using Sphinx to generate pdf files from rst files. Sphinx automatically generates section numbers up to level 3 headings, as well as Table of Content up to this level. However, I want the headings at all levels being numbered and be in the TOC. In order to do that, I am trying to use .. sectnum:: (http://docutils.sourceforge.net/docs/ref/rst/directives.html#table-of-contents). The result is not exactly what I expected:
There is a number 1. being added in front of all section numbers in both TOC and text, that is, instead of 1, it's 1.1, instead of 2, it's 1.2.
In both TOC and text up to the third-level heading, the section numbers sort of get repeated, i.e. there is a section number (a correct one) in front of the wrong one (with 1. added in the front).
Here is my sample rst file:
.. sectnum::
level 1: the first party
========================
level 1 desc: this document is about xyz
level 2
-------
level 2 desc
level 3
~~~~~~~~
level 3 content
level 4
^^^^^^^^
level 4 content
level 5
''''''''
level 5 content jflkasjfslkajf
asdfsafs
level 1: the second part
========================
fjsdafjskalfjslkafjksaljflksaj
fasdhfkjsahfjkhdsf
level 2
-------
level 2 desc
level 3
~~~~~~~~
level 3 content
level 4
^^^^^^^^
level 4 content
level 5
''''''''
level 5 content jflkasjfslkajf
asdfsafs
Here is the result of TOC:
(I took a shot of my pdf file to show the result, but I just found out that I couldn't post images because I need 10 reputation for that, this is my first time posting anything)
1 1.1 level 1: the first party
1.1 1.1.1 level 2
2 1.2 level 1: the second part
2.1 1.2.1 level 2
Here is the result of the text:
1.1 LEVEL 1: THE FIRST PARTY
level 1 desc: this document is about xyz
1.1 1.1.1 level 2
level 2 desc
1.1.1 1.1.1.1 level 3
level 3 content
1.1.1.1.1 level 4
level 4 content
1.1.1.1.1.1 level 5
level 5 content jflkasjfslkajf asdfsafs
As you can see, there is 1. added to the section number, and there is a repeated part for the headings up to level 3.
Sphinx seems to take the view that the whole project is one document, and every .rst file is one chapter of it; you can indicate the order of the files in your main .. toctree:: . I guess that's why you get the numbers. I'm guessing it's a pretty common use case not to want .rst files numbered, though, so maybe someone should propose that.
By the way, note that Sphinx explicitly does not support sectnum. Instead, they recommend you use the :numbered: parameter in the top-level .. toctree::. (http://sphinx-doc.org/rest.html)
I try your code rendered to HTML and it works fine.
maybe you can consider HTML format.
In addition,
.. sectnum::
and
.. toctree::
:numbered:
I think they aren't different, depends on your design to choose.
just want subsection to be numbered: sectnum
entire project's heading with numbered (it will auto contain sub toctree) choose: toctree:: :number:
Learn more > toctree number
Related
I am compiling a bookdown::gitbook and want to include a "References" header for each chapter in the TOC.
Currently, I have included a level 2 header titled "References" at the end of each chapter which appears in the TOC, however in-text there are two "References" headers: my level 2 header and a (level 3?) header which gets added once you build the book.
I want a (linked) References header in the TOC, and I only want one header in the text. I assume the options include:
Add the automatically included (level 3?) header to the TOC, or
Remove the level 3 header altogether, and just use my own level 2 header.
Is there a way to achieve either of these 2 points? I think I would prefer a solution to option 2, so that then the name and formatting of the header may be changed (font, colour, size etc) in line with the rest of the level 2 headers in the book.
This is a screenshot of my book. The header underlined in red is the level 2 header I have included, and the one circled in cyan is the level 3(?) one which is automatically added (as you can see it is slightly smaller than the one underlined in red).
I have recreated the issue with the demo book from here https://bookdown.org/yihui/bookdown/get-started.html, and have tried the following:
To include the level 3 header in the TOC
https://stackoverflow.com/a/69545034/13478749
header_includes:
- \usepackage[nottoc,numbib]{tocbibind}
This had no effect.
To include the level 3 header in the TOC
https://stackoverflow.com/a/51575615/13478749
bookdown::render_book("index.Rmd", "bookdown::gitbook", output_options=list(toc_bib = TRUE))
This had no effect.
So I thought I could at least try and change the name of the automatic level 3 header using this in the YAML, but it resulted in an error.
https://stackoverflow.com/a/64276396/13478749
---
reference-section-title: Referencias
---
Error in vapply(idx2, character(1), FUN = function(i) head(nms[idx > i], :
values must be length 1,
but FUN(X[[8]]) result is length 0
Calls: <Anonymous> ... <Anonymous> -> <Anonymous> -> split_chapters -> vapply
Execution halted
Exited with status 1.
But if I include an empty string as the new title, there is no error, but the level 3 "References" header remains (I assume R ignores reference-section-title because it is empty).
---
reference-section-title: ' '
---
And this answer https://stackoverflow.com/a/51494840/13478749 (and the cited bookdown documentation https://bookdown.org/yihui/bookdown/citations.html) refers to the name of the final chapter in the book, which you add in yourself as a level 1 header anyway, rather than the automatically-added level 3 header at the end of each chapter.
if (knitr::is_html_output()) '# Literatur {-}'
I have a set of three related documents in Sphinx (4.2.0). The top-level table of contents looks like this:
.. toctree::
:maxdepth: 2
Requirements_Specification/index.rst
User_Guide/index.rst
Release_Report/index.rst
In conf.py, I have:
numfig = True
numfig_secnum_depth = 1
This numbers all the figures and tables consecutively across the three documents. For example, if there are 10 figures in each document, then:
the figures in the Requirements Specification doc are numbered 1 to 10
the figures in the User Guide doc are numbered 11 to 20
the figures in the Release Report doc are numbered 21 to 30.
Instead, I would like the numbering to start at 1 in each doc, so in this example each doc would have figures numbered 1 to 10. Is there some way of achieving this?
I've tried putting :numbered: in the toctree directive, but that treats each doc as a chapter (i.e. Requirements Specification is chapter 1, User Guide is chapter 2, Release Report is chapter 3). I need each doc to be able to stand alone. I build the docs both as one set of HTML and also as three separate PDFs.
I have an RST document like this:
Introduction
------------
Some intro text.
Next Level Stuff
----------------
1. The first list item
2. The second list item
3. The third list item
I'm trying either a :numbered: toctree or .. sectnum:: to number the sections of my document, and have the numbered list inherit the section number. I'm trying to get a result like this:
1. Introduction
2. Next Level Stuff
2.1 The first list item
2.2 The second list item
2.3 The thirst list item
Is this structure supported in RST?
I am making a series of design documents in Sphinx and I would like to include them together in a toctree and have the sections within the documents numbered. I know that I can use .. sectnum:: to number all sections in the child pages. However, Sphinx/rst numbers the title of the page (which is really just the first section) and the table of contents ends up looking like:
Table of Contents
1 Design the First
2 Design the Second
and each child page looks like:
1 Design the First
1.1 First Section
1.2 Second Section
What I want is a table of contents on my index page that just lists the title
Table of Contents
Design The First
Design the Second
and child page that look like
Design the First
1 First Section
2 Second Section
Is there a way to have a title that shows up in the TOC as well as on the top of a child page which does not end up being a numbered section?
I don't know what you ended up doing, but I wanted to do the exact same thing! I had the following setup:
index.rst
.. toctree::
assignment
library_api
I only wanted the assignment part to have numbers, so either could have done two separate toctree with one using :numbered:, or put at the top of the file
.. sectnum::
:start: 0
Giving of course the exact problem you mention -- my top-level title was Assignment Writeup, so that was 0 and everything below it in subsections was 0.x e.g.
Assignment Writeup
==================
First Task
----------
Second Task
-----------
gives
0. Assignment Writeup
0.1 First Task
0.2 Second Task
as it turns out, there's an easy hack you can do. It makes things more modular than probably desired, but "add a layer of indirection".
So now I have assignment.rst and assignment_writeup.rst. assignment.rst just basically has a title and a toctree:
Assignment Writeup
==================
.. toctree::
:maxdepth: 4
assignment_writeup
then take all sub-sections and put them in assignment_writeup and "upcast" their heading level. So I now take all subsections and make them sections, and subsub and make them sub.
.. sectnum::
:start: 0
First Task
==========
^^^ === instead of --- now
Second Task
===========
and we now finally have
Assignment Writeup
0. First Task
1. Second Task
kind of dubious, but this was the only way I could achieve it x0 I wonder what you did between asking this and now? Hopefully somebody will see this and benefit one day!
Note: this has undesireable side-effects. The Assignment Writeup shows up on its own page, with just Links to the indirect document. Not sure which is worse honestly...
In MediaWiki (wikipedia's) wiki syntax, is there a way to have a numbered list with a code block in the middle?
For example:
# Number 1
# Number 2
Indented section that will become a code block
# Number 3
# Number 4
What happens in MediaWiki is you end up with something like this:
1. Number 1
2. Number 2
Indented section that will become a code block
1. Number 3
2. Number 4
(Note how "Number 3" and "Number 4" are reset as 1 and 2... It looks like StackOverflow is much smarter than MediaWiki, i had to put my example in PRE tags to make it screw up!)
I know you can indent text using "#:" syntax...
# Number 1
# Number 2
#: Indented section that will merely be indented
# Number 3
# Number 4
...but I really would like to get the same visual CSS class for my code even if it's in a numbered list.
It gets even more entertaining with nested lists. This syntax...
# MainEntry 1
## Number 1
## Number 2
# MainEntry 2
## Number 1
## Number 2
Indented section that will become a code block
## Number 3
## Number 4
...becomes...
1. MainEntry 1
1. Number 1
2. Number 2
2. MainEntry 2
1. Number 1
2. Number 2
Indented section that will become a code block
1. 1. Number 3
2. Number 4
(Note how "Number 3" is now "1. 1.")
You could try the following wiki syntax, it works for me on 1.17
# one
#:<pre>
#::some stuff
#::some more stuff</pre>
# two
It is not perfect, because you end up with a more indent but it does allow one to use the wiki syntax for correctly formatted pre blocks over multiple lines.
As previously mentioned, the other proper way would be to use HTML mark up.
<ol>
<li>one</li>
<li>two</li>
<pre>some stuff
some more stuff</pre>
<li>three</li>
</ol>
Use html:
<ol>
<li>Coffee</li>
<li>Tea</li>
<li>Milk</li>
</ol>
it will work in mediawiki.
Note from the example that I posted below, it is the </li> that makes it work properly.
This works fine in MediaWiki 1.17.0:
===Alternative way of using pre in numbered lists.===
# Numbered line 1.
# Numbered line 2.<pre>code line 1
code line 2</pre>
# Numbered line 3.
The secret is to replace the newlines with the
entity and write everything in one line.
Your issue is the subject of two bugs filled in the MediaWiki bug tracker in late 2004 and 2005 :
Bug 1115 - Newline as list item terminator is troublesome
Bug 1584 - Need method for multiparagraph list items, continuing numbered lists, and assigning specific numbers to list items
By reading them, you will find the solution is to not use the MediaWiki syntax but to rely on "pure" HTML.
I'm suggesting a different answer: don't do it.
I've attempted to use all the workarounds for this basic Mediawiki issue and found that they are all very imperfect. I've learned to live without numbers, and instead:
Use the splat (*) instead of (#) for all my lists
Continue to use the leading space for all my code blocks
This is far far simpler and maintainable than any workaround. Besides, use of any reference to a number is subject to change as the steps are edited - and this then becomes another maintenance issue.
In the above example the second indentation (::) is not necessary.
Just one indentation works fine (:) as follows:
# one
#:<pre>
#:some stuff
#:some more stuff</pre>
# two
Produces:
1. one
some stuff (just one indent level, not two)
some more stuff
2. two
You can also try adding a "blockquote" tag surrounding the "pre" tag, makes it look a little more polished.
== HAProxy Configuration ==
#'''File:''' /etc/haproxy/haproxy.cfg
<blockquote>
<pre>
global
log 127.0.0.1 local1 notice
maxconn 4096
#daemon
debug
crt-base /usr/local/haproxy/ssl
</pre>
</blockquote>
Which will indent the gray box in line with your bullets/numbers without using colons.