Following my other question Show/hide part of text (question/answer) in sphinx file what I would like to do is to export an html (or whatever format) without this tag (e.g. an html without all the admonition directives.
I read the .. only:: directive but it seems that you I can exclude an entire page from an html and let it in the latex for example.
You can nest directives by indenting them under one another.
.. only:: html
.. admonition:: Solution
:class: toggle
* Go to the dexterity-controlpanel (http://localhost:8080/Plone/##dexterity-types)
* Click on *Page* (http://127.0.0.1:8080/Plone/dexterity-types/Document)
* Select the tab *Behaviors* (http://127.0.0.1:8080/Plone/dexterity-types/Document/##behaviors)
* Check the box next to *Lead Image* and save.
Related
I am using CKEditor 5, Inline Editor with Markdown and Superscript plugins. As per the git documentation superscript is represented as <sup></sup> in markdown. Setting the data via editor works perfectly.
Example: editor.setData("* **Per** modified decision <sup>tree</sup>.")
However, editor.getData() returns the markdown without the sup tags. * **Per** modified decision tree.
How can I configure the editor to allow tags in the markdown data returned?
This would retain the 'sup' or any other html tags in the markdown output.
editor.data.processor.keepHtml('sup')
Context
I am using Sphinx to create technical documentation (not code-related). The input are several reStructuredText and SVG files. The output is created using the singlehtml builder (which is converted to PDF using weasyprint in a later step).
Problem
I would like to include a table of contents (TOC) in the final document. The default location for the TOC (sidebar) is not an option. I have to disable/hide the sidebar to generate a useful PDF.
Solutions (I have considered / tried)
toctree directive: Seems to only work with the sidebar, no matter what I try.
HTML Theming: I'm using it for styling the HTML output, but I would not know how to address the TOC issue.
Sphinx extensions: I wrote my own, but it's not very flexible and I'm still sure that others have already solved this problem.
Use latexpdf builder: Tried that and it solves the TOC problem, but it creates a few other problems and styling the document is so much easier for me using CSS.
Other tool than Sphinx: Is this a typical case of an XY problem? I would like to use reStructuredText and SVGs to generate a PDF, but I would be open to use something else than Sphinx.
Use the contents directive.
Here's the directive in its simplest form:
.. contents::
Language-dependent boilerplate text will be used for the title. The English default title text is "Contents".
An explicit title may be specified:
.. contents:: Table of Contents
As #mzjn already suspected, .. contents:: only lists the contents of the current file, but if I use .. include:: instead of .. toctree:: to include other documents, it works nevertheless. So what I'm currently using is this:
.. sectnum::
.. contents:: Table of Contents
:depth: 2
.. include:: intro.rst
.. include:: processes.rst
How to display a warning box in the html generated using the sphinx-build?
Warning
Do not use the directives sectnum, header and footer.
I want to show the above message as something like this:
(apologies, SO doesn't allow me to embed the image in the post here)
Please ignore the text formatting, my main aim to show a box with some text to get the attention of the user like on sphinx-doc site
The reStructuredText syntax you want is for things called admonition directives.
That specific example exists in the documentation source:
.. warning::
Do *not* use the directives :dudir:`sectnum`, :dudir:`header` and
:dudir:`footer`.
Is there a way to add a tag to the format dropdown that would wrap the text in <small></small> tags?
Editing config.js as follows causes a runtime error:
config.format_tags = 'small;p;h1;h2;h3;pre';
probably because <small> is not block level?
The reason of the runtime error is, that js can not find CKEDITOR.config.format_small.
You have to do two things:
Search for CKEDITOR.config.format_h6 in ckeditor.js and add CKEDITOR.config.format_small={element:"small"};. Then the error is gone, but you can not see the entry yet.
open the languagefile you want (e.g. en.js) and add "tag_small":"small text".
now CKEditor supports the small tag.
This works for me, I hope it works for you too.
If I want to add a custom section tag to format tags, this work for me:
1. Go to config.js, add
config.format_tags = 'h1;h2;h3;h4;h5;h6;section';
config.format_section = { element : 'section' };
2. Then open the languagefile you want (e.g. en.js) -> lang/en.js
search for "tag_pre":"Formatted", and add "tag_section":"Section".
If you're looking to wrap text in a certain tag, you can also achieve this with the Style dropdown as well.
First, configure your editor to allow styles at /admin/config/content/formats/manage/full_html. Replace full_html with whatever editor version you want to modify
Drag the Styles button to the active toolbar if it isn't already there
Add items to "Styles Dropdown" tab under CKEditor plugin settings
Each option takes the form css_selector | Human Visible Name so in your case, you'd add small.my_element_class | Super Special Small or something similar.
Instructions abbreviated from this post: https://www.axelerant.com/resources/team-blog/drupal-8-custom-styles-in-ckeditor
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.