I know that I can use :sectnums: all after the title to enable section and subsection numbering. But is it possible to define this in the theme yml? I have a lot documents which use the same theme file, and it would be nice to have it defined only once.
Related
I couldn't find a directive that handles this.
Suppose to have a single rst document and for some reason you want to hide a single section during the build (no matter if HTML, PDF..), like:
Visible section
===============
Here some example I want to show
Not visible section
===================
Some text that I have written but for the current build I want to hide from the final document
is there a .. hidden:: directive that handle this, I'm thinking of something like:
Visible section
================
Here some example I want to show
.. hidden::
Not visible section
===================
Some text that I have written but for the current build I want to hide from the final document
.. visible::
Another section
===============
Other visible section in both text and final document
You can use comment syntax: http://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#comments
The version of Sphinx I have got automatically generates an index.rst file that starts with a comment like this:
.. sphinx-quickstart on Sat Jun 22 15:48:19 2019.
You can adapt this file completely to your liking, etc
It does not show up in the documentation. You can start lines with two dots and a space followed by your own text and that does not show up either. You need to make sure that all the lines you create are indented the same as the first line. Then the whole section does not show up. Also make sure there is an empty line before the section and after it (unless it is the first section in the file or the last one)
Here is a solution to hide a section, so it doesn't show up in the HTML ouput.
However, this does not affect the build.
The idea is to use the class diretive and that way be able to assign a CSS class to the section(s). In CSS you can then define the class with display: none (or any other CSS).
For you example it would look like (note the identation):
Visible section
================
Here some example I want to show
.. class:: hidden
Not visible section
===================
Some text that I have written but for the current build I want to hide from the final document
Another section
===============
Other visible section in both text and final document
In your css you add the following styling:
.hidden { display: none }
Here is a link that explains how to add custom CSS to Sphinx.
I want to modify the "Format" dropdown for CKEditor within Mura, because I don't like the way Mura renames the headings. For example, an <h2> element is renamed to "Heading", and an <h3> element is renamed to "Heading 2". I get why they did this, because the <h1> is reserved for the page title, but it's confusing for content editors and accessibility.
I want to remove this renaming feature.
I believe the naming being used (like "Heading 1") is part of the CKEditor itself (reference).
As far as which HTML tag is actually used for those formats, Mura allows you to customize that. Look at the contentRenderer.cfc file under your theme's folder. Within that file they are setting variables that are used to customize the editor and page layouts. Specifically this section (reference):
// The following settings allow developers to change logical page structure.
// For example, some developers prefer H1 tags for their page titles,
// some prefer H2 tags - you can adjust this here:
this.headline='h2';
this.subHead1='h3';
this.subHead2='h4';
this.subHead3='h5';
this.subHead4='h6';
I'm not 100% sure but I think those settings are also used within the CKEditor in Mura.
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
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.
I am using Confluence 4.0.3, I am trying to create a PDF layout/stylesheet so that it would grab the main title from the page content and move it to the title page.
What I have tried so far:
use the way that confluence suggests - it did not work well at all because it came with extra toc (np, I can hide it) and extra page content because it requires me to export from the parent level for it to work
I define a macro which contains the page title and I can use css to make it land on the title page. This works however if I was to export multiple docs this could pose a issue
Style the h1:first-child, this works but again on multiple docs this would be an issue.
Question: Is there a good way to do this on multiple doc exports? If not, does the page title have its own class that I can target instead of the h1:first-child? I tried h1.pagetitle (in their documentation) but it does not work, thanks
I used a user defined macro to put the title in and use the PDF export css to position it on the title page. This works as long as you are only exporting 1 document at the exporting level. If you are exporting 2 or more docs from the same exporting level then you can only define 1 of the macros or else they will all be at the same position on the title page.
This seems like the easiest way I found to implement something like this.
I would try employing a minor work-around. You could use a .asp page, which is located off of confluence, to pull the the pdf title and display it how you like. Then you can use an html-include macro to display the .asp page, and the pdf title it shows, wherever you like on confluence.