I made a Sphinx project with an index file and two other rst files called firstdoc.rst and seconddoc.rst. My index.rst has the following toctree:
.. toctree::
:maxdepth: 2
:caption: Contents:
firstdoc
seconddoc
I ran make html after adding the firstdoc.rst and then again after adding seconddoc.rst.
Now when I transfer the _build/html directory to a server I find that the index page has a side bar which lists both the firstdoc and seconddoc pages. The firstdoc page does not list any pages in the side bar. The seconddoc page lists the firstdoc page but not the seconddoc page in the side bar.
I want all the pages to list all the pages in the sidebar. How should I go about this?
Edit: If I edit the firstdoc.rst and seconddoc.rst files and then run make html and then transfer firstdoc.html and seconddoc.html to the server then I get what I want. That is all the pages are shown in the sidebar of all the pages. This seems very unsatisfactory as it means every time I add a new page to my project I have to edit all the existing pages in the project in order for them to include the new page in their side bar. Is there a more convenient way?
The general rule is that the .. toctree:: on your index page (the page set as master_doc in conf.py) will control the structure of the sidebar on all documents, so the :maxdepth: option set there will control the sidebar's depth as it displays on all pages.
Make sure you run make clean and double check all the build files are deleted, it should work. Your note that editing the files before the build solves it hints that intermediate build files are being cached.
Related
I'm using the sphinx documentation system to generate reports in both HTML and Latex output formats. So have a hierarchical structure where I have a read index.rst which contains a toctree that references all chapters in order of appearance. Then a chapter is a folder which also contains an index.rst with only a header and a toctree which includes all sections for that chapter.
So as an example my structure looks likes this:
root
- index.rst <- Contains only a toctree that references other chapters index.rst.
- SomeChapter
- index.rst <- Contains heading and toctree that references actual content
- section1.rst <- actual content
- section2.rst <- actual content
....
This renders beautifully with latex since you will literally get someChapter and below that the sections but in html those are all seperate pages which get's boring quick for some smaller subsections since you have to keep clicking around. Is there a way to instruct the html builder that in some cases it should show the subpages in the same page where they are in the toctree and not create subpages for it?
I know about singlehtml but that does build an entire single html page for it and I want to do it partially because a lot of times different chapters are great with different pages but sections can be easily on the same page.
Any help is appreciated.
Untested answer.
Have two different index pages, one for HTML (index.rst) and LaTeX (indexlatex.rst), where the latter is a copy of the former, then the former gets modified.
Then in your conf.py, specify indexlatex.rst as the entry toctree. Example from Pyramid:
latex_documents = [
('latexindex', 'pyramid.tex',
...
)
Finally to modify index.rst, you would use a series of include directives and remove the toctree directive.
.. include:: section1.rst
.. include:: section2.rst
You might also need to use :orphan: metadata on the latexindex file to suppress warnings about it not being included in the index's toctree.
I have just recently (yesterday) started using sphinx and read the docs for my project.
Till now I am happy with the Html documentation but the pdf version includes all the articles That appear in the index within the Contents heading. And the Documents orignal content/index is simply comprised of two links.
Please help.
The documentation is at http://todx.rtfd.io and the pdf is here.
When generating the PDF, Sphinx is always adding the content that is referenced via a .. toctree:: directive exactly where the directive is placed.
In contrast, when generating HTML, Sphinx is placing the content after the file that contains the toctree.
In this aspect, PDF generation and HTML generation are simply inconsistent.
Thus, you should place all content of the index page before the table of contents.
In case you want to provide an overview of the most important sections inline, you can use a list of references. Then, you might want to hide the toctree using the hidden property, for example like this:
Contents
--------
- :ref:`quickstart`
- :ref:`userguide`
Features
--------
- Fast
- Simple
- Inituitive
- Easy to Use
- Offline
- Open Source
.. toctree::
:hidden:
quickstart
userguide
We are considering using Sphinx where I work and it appears to do everything we need. However, I am having issues getting it to match the required corporate template, which requires there to be some front matter pages inserted between the title page and table of contents.
If text is text is placed above the master table of contents in the .rst file, then it is placed above the TOC in the HTML output, but it is moved to below the TOC in the pdf output. I've also tried adding a hidden toc, but that didn't work either. The content also gets placed after the non-hidden toc.
.. toctree::
:hidden:
frontmatter
.. toctree::
:maxdepth: 2
contents_of_document
I know this has to be possible since people have published books using this tool, but I can't figure out how to do it.
I've tried this with sphinx 1.4.0 and 1.4.1. Is this something I need to add a latex sty or cls file to make it work? I would prefer not to since we would like to use both the HTML and PDF outputs.
Thanks
It looks like I need to RTFM. It is in chapter 10 to of the sphinx manual:
’tableofcontents’ “tableofcontents” call, default ’\tableofcontents’. Override if you want to generate a different table of contents or put content between the title page and the TOC.
So it order to do this, you need to learn some LaTeX as you will have to manually (or programmatically) write the from matter separately from the reST documentation.
I'm generating html documentation in Sphinx.
How do I modify the sidebar for each of the html pages in my document so that they include the toctree? By default the toctree only seems to display in the master_doc page, and only in the main area instead of the sidebar.
Is there an easy way to do this? I'll be using readthedocs to host the generated documentation, so I would prefer to avoid the use of any third-party plugins, unless they are also available on readthedocs.
You can customize your html sidebar in conf.py.
The default html sidebar consists of 4 templates:
['localtoc.html', 'relations.html', 'sourcelink.html', 'searchbox.html']
In conf.py you could change localtoc.html to globaltoc.html like this:
html_sidebars = { '**': ['globaltoc.html', 'relations.html', 'sourcelink.html', 'searchbox.html'] }
Since this in the end this will be used in HTML files, this should work on ReadTheDocs.
Including the 'globaltoc.html' has a drawback in that it doesn't show both the global and local toc for the page you're viewing.
It appears that others were irked about this limitation and resulted in the subsequent development of an extension to support a full toc in the sidebar, checkout: https://pypi.python.org/pypi/sphinxcontrib-fulltoc
Nothing will appear in the "Navigation" section of the default Sphinx sidebar until you add the names of files that you want to scan for section headings to the toctree:: directive in your .rst file.
For example, if you want all the headings of your index.rst file to appear in the Navigation pane, write index (without the extension) in the toctree:: list like so:
My Level 1 Heading
==================
Glorious content.
My Level 2 Heading
------------------
More content
.. toctree::
:maxdepth: 2
:caption: Contents:
index
The crucial bit is adding index right there at the end. If you're like me, you start your projects with the auto-generated template from sphinx-quickstart, which (at time of writing) populates your .rst files with EMPTY toctrees.
there are tutorials on the web about gow to create index.html, css file and template.xml that contain placeholders. ok, i got it, it's simple. but i need a template that has some different views. for example:
-all pages have a topmenu, header, left sidebar, mainarea and a footer but:
-first page has no header .topmenu after which sidebar, mainarea and footer comes.
-second page has sidebar moved from left to right
-third page has four blocks (blocks for special offers) instead of mainarea.
as far as i can see, i need to create three standalone templates with unique set of placeholders for each template. because i can't see the way to change laarge mainarea placeholder with four placeholders for offers blocks on some pages. dynamically.
is there if-statements in joomla templates to simply determine a document id to view four placeholders instead of mainarea. or to not show header on the main page (f.e. doc. id="mainpage")
but i want it to be selectable like:
-this page has first case of that template (index_1.php)
-and that page has a second case of the same template (index_2.php)
like a selectbox.
is that possible?
I will make this an answer as opposed to a comment since I believe it will do what you are looking for.
Once your articles are setup and your links to them are established (the site has the info on it you're looking for), you can create the modules containing the data that you want shown from time to time.
Go to the module manager - on the right you should see 'module assignment' or something along the lines of 'display this module on the following pages'; you can then pick which pages you want the module to show on. You can specify all pages, none, specific pages, however you want.
This will enable you to show them only where needed however you like.
You can ALSO do this programatically inside the module (if you do custom HTML and use an extension like Sourcerer to add PHP to the module) with PHP should you want a little more flexibility, but just choosing the pages to show on should work for what you're doing.