I have a problem with using Sphinx-doc's :ref: role, I put a label above a paragraph and then I try to link to that label from another doc but inside the same project.
The label I use in one document:
.. _hal_1k_1p:
And the ref I try to use to link to that label:
:ref:`Link title hal_1k_1p`
But I only get this error message when building the doc:
WARNING: undefined label: link title hal_1k_1p (if the link has no
caption the label must precede a section header)
What am I doing wrong?
Okay, looking at :ref: you need to have this:
:ref:`Link title <ha1_1k_1p>`
to link to that label.
Ensure you have angle brackets surrounding your label like so: <label>
First make sure that your ref is in the format:
Label:
.. _yourlabel:
Reference:
This is a reference to :ref:`yourlabel`.
or (if you want to give it a custom name)
This is a reference to :ref:`my very own label <yourlabel>`.
The label definition contains the leading underscore (_) while the reference doesn't! Also make sure that you didn't accidentally copy the colons from the label definition (:) to the reference.
If that doesn't help try switching languages back to english temporarily in your conf.py:
language = 'en'
If you see that this works you can switch back. Somehow this solved my problem. Maybe related to: https://github.com/sphinx-doc/sphinx/issues/1300
Related
I'm writing some text that will be converted to HTML, as a long single page.
Can't figure out how to make links to sections as in HTML using #some-id, so that a user when clicking it will go up or down the web page to
<h2 id="some-id">Section A</h2>
<p>Lot's of lines</p>
Go to section
What you're referring to is called an "internal cross reference".
The markup for an internal cross reference is:
<<id,caption>>
where id is an element on the page that has an identifier, typically a title, and caption is optional text that should appear in the link.
You can link to titles that have auto-generated ids, but the formation of the ids could vary based on the attributes idprefix and (for Asciidoctor) idseparator. The default is to make the title text lowercase, prefix with an underscore, and replace spaces and other punctuation with underscores. The id for the title "Let's make a game!" would be _lets_make_a_game.
It is often better for you to specify your own id that will remain stable even if you edit the text of a title. You can do so with:
[[id,label]]
where id is the identifier you want to specify, and label is the optional, default label that may be used for the cross reference (if the cross reference itself doesn't specify a caption).
If the element that your cross reference points to is a title, you can omit the caption and the label, and the link will use the title's text as its own text.
For Asciidoc, see: http://asciidoc.org/userguide.html#_internal_cross_references
For Asciidoctor, see: https://asciidoctor.org/docs/user-manual/#internal-cross-references
Usage Example:
This is how we assign an ID:
== Debug Running Pods [[debug_running_pods]]
Refer to an ID:
<<debug_running_pods>>
Another option is to use the link: macro. Here's an example from one of my Asciidoctor docs:
link:#_explore_the_public_directory[17.4. Explore the `public` directory]
Info about this is in https://asciidoctor.org/docs/user-manual/#url. Here's an excerpt from the relevant part:
When a URL does not start with one of the common schemes, or the URL is not surrounded by word boundaries, you must use the link macro.
Is it possible to create an intra-document link with sphinx, such that the displayed text is independent of the link and destination?
Currently, I make intra-document links like so:
.. _Label_For_Section:
===============
Name Of Section
===============
The link :ref:`Label_For_Section` is rendered as "Name Of Section".
The link Label_For_Section_ is rendered as "Label_For_Section".
What I want is a way to have a link, where the destination text, link label, and displayed link text can all be different strings. Eg a link to a section called "A" with a label .. _B: which is rendered as "C"
Note
I noticed that other kinds of links (eg external hyperlinks) are similarly constrained, and I figure the solutions may look similar, however I am looking specifically for a solution for intra-document links.
See Cross-referencing arbitrary locations, specifically the ref role.
:ref:`Link title <label-name>`
In code, the NSLocalizedString macro lets you give a descriptive comment along with your string, so your translators have the necessary context to write a translation. However, I don't see any way to give an equivalent comment along with the strings in my storyboard. Instead, the xliff file contains notes like this:
Class = "NSTextFieldCell"; title = "Created"; ObjectID = "1u4-pn-J7a";
Not very useful. Is there any way for me to provide my translators with better explanations of the purpose/placement of these strings?
There is a way to do this. In the Identity inspector, under Document, there is a section called Notes. Text added to this section will be included in the <note> section of an item in the xliff file.
Inside the section you can also add text= and then whatever you want to tell the translator.
Alternatively, if you end up working out of a text file, you can also add a note above or below the string inside forwarded slashes e.g.
"00_bkm_11"="Bookmark";
/Used to mean save a webpage in the app/
Hope these two help :-)
In the RST syntax, you can specify a :target: attribute for setting a link. I would like to link the image to a "materials.rst" doc page, whose main section title is "Materials"
But neither of these work as target value:
:target: `materials`_
:target: :doc: materials
:target: materials
How can I achieve this?
Not fixed even after 6 years, although :ref: works now across files just fine. However, you can't use :ref: within image or figure directives.
try using this:
:target: materials.html
...and hope for the best! The :target: role seems to accept HTML links only.
Let's assume there is some file named doc.rst which I want to access via the thumbnail in another document:
.. _doc:
Some Title
==========
...and then, in another document, I use the following solutions:
.. image:: /media/thumbnail_of_my_doc.jpg
:ref:`doc` <- doesn't compute
:target: doc (or doc.rst, or doc_) <- doesn't work either
:target: doc.html <- works im my case
The last option works just because I assumed the name of the HTML to be generated. What if I was wrong? This is a pure hack.
I can't believe no one got bothered to fix this.
I use RTD theme on Sphinx 4.2.0. all is updated to the newest versions.
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