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.
Related
I am a beginner at asciidoc. I have structured my project into modular files so it is easier to manage. And I am able to generate the pdf using asciidoctor. However, the toc does not include the list of files it gets through the include directive.
Here is the main file:
= Booktitle
Vinay <email>
:sectnums:
:toc:
:toclevels:
:leveloffset: 1
include::chapters/chapter_00.adoc
include::chapters/chapter_01.adoc
include::chapters/chapter_02.adoc
:leveloffset: 0
Index
======
And here is chapter_01.adoc:
= The First Chapter
This is the first chapter.
The table of contents only includes a link to the Index. What am I doing wrong?
The command I used is: asciidoctor-pdf book.adoc
Your include is missing a pair of square brackets. For a book that has a title page, you might want to set the doctype attribute to book. The attribute toclevel should be set to a number indicating the heading levels you want to list in your table of contents. If you leave it empty, the table of contents will be empty.
Tested with Asciidoctor PDF 1.5.3 using Asciidoctor 2.0.10, the following worked for me:
= Booktitle
Vinay <email>
:sectnums:
:toc:
:toclevels: 2
:doctype: book
:leveloffset: 1
include::chapters/chapter_00.adoc[]
include::chapters/chapter_01.adoc[]
include::chapters/chapter_02.adoc[]
:leveloffset: 0
[Index]
= Index
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...
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
I can express
3rd page is the title page
in YAML
title: 3
What about the following?
Pages 10 to 15 contains chapter 1
One way is
chapter 1: [10, 11, 12, 13, 14, 15]
I would prefer a range here. Is there anything like that in YAML?
chapter 1: (10..15)
** Update **
The following would be my alternative if there is no such thing as range in YAML
chapter 1:
start page: 10
end page: 15
There is not direct way to specify ranges in YAML, but some YAML can store serialized objects, for example in Ruby:
...
normal range: !ruby/range 10..20
exclusive range: !ruby/range 11...20
negative range: !ruby/range -1..-5
...
Look here
Range is application specific. The following may be meaningful for some applications:
-1 .. Q
a .. Щ
23 .. -23.45
1 .. 12:01:14 (both are integers in YAML !)
But the ruby way is also unclear since it does not say whether the end values are included or not: 10 .. 15
(Are you only talking about ranges of integers ?)
Andrey is right - there is no such thing as a basic range. Ranges can be defined on top of totally ordered data types. YAML does not even know the concept of ordering so it makes no sense to talk about ranges in YAML. YAML only knows the concept of node types, the concept of equality, and some predefined kinds of links between nodes. By the way I don't know any other data serialization lange (JSON, XML, CSV, Hessian, Protocol Buffers...) that natively supports ranges.
Just out of curiosity, is there a name for the kind of navigation I've been working on?
It looks like this:
<<first <previous 1 2 3 4 5 [...] 20 next> last>>
i.e. navigation where you've got x pages, but you don't want to show x links, you want to limit the amount of space taken up, so you show y links at a time, and indicate the existence of the other pages with an elision.
At some point in the middle, it would look like this:
<<first <previous [...] 8 9 10 11 12 [...] 20 next> last>>
with elisions on both sides.
Answering to just clear up this question. I hereby declare that it has no official name.
I also hereby make up the name 'elided pagination' for it.
It's called web pagination, search result pagination.
thresholded navigation pager?
Not sure what the ordinary version of this pagination scheme is called (if anything).
However, I came up with an advanced version of it capable of handling very large numbers of pages (where ellipses (...) skip successively larger blocks of pages as you get further away from either the current page or the endpoints).
I called my scheme "Logarithmic pagination" or "Logarithmic page navigation".
You can find it (with implementation) on stackoverflow here.