When inserting a document in a toctree, the link displayed is the main title of the document. So when I do:
.. toctree::
materials/diffuse
materials/glossy
materials/specular
I get:
Materials
Diffuse material
Glossy material
Specular material
The word "material" is clearly redundant in the toctree, but is important in the document titles for good understanding.
RST allows me to write this:
.. toctree::
Diffuse<materials/diffuse>
Glossy<materials/glossy>
Specular<materials/specular>
But I do not like this, as renaming a document requires updating the index toctree, and link updating is why I went from MediaWiki to Sphinx. Also, this disables the use of :glob: and wildcards in the toctree
Question: Is there any way to specify a toctree title in the leaf document itself, for instance in "diffuse.rst", as a meta-property?
Thanks!
In concept, the css content property would be applicable here. Assuming your title is rendered with <h1> element, you'd want something like this:
.. raw:: html
<style>
h1:after {
content: " Material";
}
</style>
The <style>...</style> block is doing the work. Your docs keep the one word titles (Diffuse, Glossy, Specular) and the css adds " Material" on render. So your pages have the title you want, and your toctree doesn't have the redundant "Material" for each item. However, you'd want that block to appear only on the pages in your "Materials" section -- you can't just add it to the main css file, or it will affect all <h1> elements. Unfortunately, Sphinx doesn't have a mechanism for properly creating a <style> block in a page's <head> section, as far as I know. Therefore to use this css technique you have to accept the complete hack of dropping it in a .. raw:: html directive as shown, somewhere on your page. It won't really matter where you put it in your doc -- any location you choose will produce non-valid html, but will render what you want: your toctree labels will not contain "material"; your page titles will.
Related
I have SVG image file with several nodes each is associated with URL. If I open this file directly in browser I can click on each node and it will open different URLs. However when I use this picture in my Sphinx documentation it doesn't work - picture rendered as a whole so I need to open it by View Image and only then I can click on nodes.
I'm using standard image directive:
.. image:: myfile.svg
Probably I need to use something else?
Sphinx generates <img> tags for images, which makes sense in most cases. However, to have the links inside the svg be clickable, you should use an <object> tag, i.e.:
.. raw:: html
<object data="myfile.svg" type="image/svg+xml"></object>
(Regarding the GitHub issue you linked to, I don't think there's a lot that Sphinx can do here—it's really quite complicated—short of introducing a new option to the .. image directive that lets the user specify whether to render as an img or object tag.)
One simple solution would be to add a link to the svg file in this .. image:: myfile.svg command:
.. image:: myfile.svg
:target: _images/myfile.svg
Take care of checking the relative directory where the images are copied when the html files are generated. By default, it should be _images/.
This way, you can click the SVG file, to see it in a plain page, and then click on it as usual (not a perfect solution but still..).
I am probably misunderstanding the OP's requirements, but why not just include the SVG into the sphinx documentation as html? This appears to work for me:
.. raw:: html
:file: images/image.svg
To include clickable svg links within sphinx I did the following:
.. raw:: html
:file: ../graphs/pymedphys_analysis.gamma.svg
See:
https://raw.githubusercontent.com/pymedphys/pymedphys/1915b9496e93782bdac7dcebff7e26e470e5ff57/docs/graphs/graphs.rst
This then freed me to write the following within an imported style sheet:
svg {
width: 100%;
}
https://github.com/pymedphys/pymedphys/blob/f4d404fa1cf3f551c4aa80ef27438f418c61a436/docs/_static/style.css
This made the svg fit the container as desired.
See:
https://pymedphys.com/developer/dependencies.html#pymedphys
I like this way
.. raw:: html
<a href="https://www.google.com/">
<img src="https://img.shields.io/static/v1?&style=plastic&logo=appveyor&label=Google&message=link2google&color=FF0000" alt="No message"/></a>
I'm still looking for a better solution myself, but I ran into the same problem and used this workaround.
You can use the download directive to give the user a link to the file.
:download:`svg <images/image.svg>`
There is a previous question that explains how to add a color span to some reStructuredText.
To recap the procedure:
First, you have the role.
.. role:: red
An example of using :red:`interpreted text`
It translates into as follows.
<p>An example of using <span class="red">interpreted text</span></p>
Now, you have the red class, you can use CSS for changing colors.
.red {
color:red;
}
How do you do this if you want text that spans multiple lines? For example:
.. role:: red
:red:`paragraph 1
paragraph 2
paragraph 3`
Where paragraph 1, 2, & 3 would all be "red". If I try to do this I get the warning message:
WARNING: Inline interpreted text or phrase reference start-string without end-string.
It doesn't create the span and inserts ":red:" into the text. It just doesn't interpret this as a string (as the warning suggests).
Basically, can this be done in reStructuredText, and if it can, how?
I'm using Sphinx 1.1.3.
There are a number of ways to do this, but one of them is to use the class directive:
.. class:: red
This is a paragraph.
This is another paragraph.
Most docutils HTML writers will put that into html output as a class html attribute, which you can then style with CSS.
In Sphinx, in particular, however, you may need to use rst-class instead of class in at least some cases. See: https://www.sphinx-doc.org/en/2.0/usage/restructuredtext/basics.html
Also, many block-level elements in RestructuredText take a :class: parameter which does pretty much the same thing.
Actually the question is in the subj...
Is it possible to make handlebars template framework, to recognize templates within a div tag and not in script tag?
For example I would like to create template with this markup:
<style>
div.text-x-handlebars {display:none;}
</style>
<div class="text-x-handlebars-template">
<h2>I'm template</h2>
<p>{{welcomeMessage}}</p>
</div>
Yes you can put your templates in <div>s rather than <script>s, for example:
http://jsfiddle.net/ambiguous/RucqP/
However, doing so is fraught with danger. If you put your template inside a <div> then the browser will interpret it as HTML before you've filled it in; so, if your template's HTML isn't valid until after it has been filled in, the browser may attempt to correct it and make a mess of things. Also, if you have id attributes in your templates, then you will end up with duplicate ids (one in the template <div> and a repeat in the filled in template that you put in the DOM) and that will cause all sorts of strange and interesting bugs. The browser will also try to download any images inside the templates in a <div>, this may or may not be a problem (if might even be desirable but probably not desirable if the image uses a template variable in its src attribute).
Basically, you can do it but you shouldn't, you should put your templates in <script id="..." type="text/x-handlebars-template"> elements instead.
Our group needs to have a standard Common Look and Feel (CLF) for all our web applications. the base line for them all is the same, and certain items like the css references can have customization.
We want to find a way to create either one full layout file or partials that can be shared by all.
I have read many postings and the layout variable on views do not have the ability to read absolute paths.
Can we get a razor method to read XML and render to our layouts, much like the renderbody() does?
EDIT:
We would like to have items like the css, standard layouts etc in one project. Then this could become a distributable package for development teams.
Example of the final output we are looking for:
_base.cshtml example.
#model CLFModel
#CLF.Header(...)
#CLF.LeftMenu(...)
#CLF.OptionalRightMenu(...)
#CLF.Body(...)
#CFL.Footer(...)
The CLF.Header would contain something like below, and would be render from either a file or a pre compiled reference.
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="#Model.dcLanguage" lang="#Model.dcLanguage">
<head>
<meta charset="utf-8" />
<title>#Model.PageTitle</title>
meta tags.....
CSS required links ....
CSS section for custom link references ...
script tags(required)
optional section for script tags
</head>
You can create as many partial view as you want and just include them into the view you are rendering using #Html.Partial("YourPartialView"). You can create a _MasteLayout, which contains various partial views and #RenderBody for maintaining a consistent feel
Say my some.rst file looks like this:
============
My Title
============
1. Section
================
2. Section
=================
After compiling, in the resulting some.html there will be a table of contents in the side bar that appears as:
My Title
Section
Section
Is there a simple way to remove 'My Title' from the table of contents in some.html?
I was able to solve this by using the .. raw:: html method as described above, with a slight tweak (that avoided breaking the auto-generated TOC). as described earlier, if your file only contains .. raw:: html headings, it will break the Sphinx auto-generated TOC. however, if you use .. raw:: html and add --------------------- below it, it won't show on the left-hand nav, and won't break the TOC.
e.g.
so i finally accidentally figured out how to get headings to not be displayed in the left-hand TOC. if your file only contains .. raw:: html h2 headings, it will break the sphinx auto-generated TOC (as mentioned in the stackoverflow article). however, if you use .. raw:: html and --------------------- below it, it won't show on the left-hand nav, and won't break the TOC :star2:
e.g.
.. raw:: html
<h2>What Can I Do With KSQL?</h2>
---------------------
The easy way is to use an object type that's ignored by the TOC directive:
.. rubric:: My Title
This creates text that looks somewhat like a heading, but is excluded from the TOC. You can update your CSS file with whatever style you want for the .rubric class, even mimicking h1 style if you like.
See "Non-TOC headings within a Restructuredtext page" for how to define rubric styled classes.
If you are trying to remove it from all of your documents, try customizing the default template. Otherwise you will need to modify the HTML builder by creating a subclass.
Very late to this party, I know. I just had this issue, needed to mimic h2 and was not able to edit the style sheet.
My solution ended up being adding raw html in the some.rst:
:raw-html:`<h1>My Title</h1>`
1. Section
================
2. Section
=================
You can make your own h3 tag.
For your header you use:
|start-h3| My title |end-h3|
Later at the end of the file you write:
.. |start-h3| raw:: html
<h3>
.. |end-h3| raw:: html
</h3>
It seems you are talking about a local TOC (a "on this page" TOC). Unfortunately, Sphinx always prints a document title as first item (<li>). Actual local TOC (section titles) are all nested <ul> inside the first document title <li>. (Yes, it is annoying.)
You have two options:
If current Sphinx theme has local TOC, you have to tweak produced HTML markup. For example, by hiding document title using CSS. Copy-pasting from https://techwriter.documatt.com/2021/sphinx-localtoc-remove-document-title.html:
.localtoc > ul {
margin: 0;
}
.localtoc > ul > li {
list-style-type: none;
}
.localtoc > ul > li > a {
display: none;
}
.localtoc > ul > li > ul {
// any additional styles to local toc <ul>
}
Alternative might be to manually print local TOC, e.g. at the beginning of a document with the contents:: directive and its :local: option. Example taken from https://restructuredtext.documatt.com/element/contents.html#no-current-document-title:
#################################
Contents without a document title
#################################
Testing ``contents::`` directive with ``:local:`` flag.
.. contents::
:local:
**********
Section L2
**********
Section L3
==========