What's the difference between a target and a reference in reStructured Text?
I'm trying to understand the reST spec and how hyperlinks work in sphinx, which is surprisingly non-intuitive.
Unfortunately, the documentation just says "to be completed" for the target and reference elements:
https://docutils.sourceforge.io/docs/ref/doctree.html#target
https://docutils.sourceforge.io/docs/ref/doctree.html#reference
What's the difference between target and reference elements in .rst files.
(Bonus: why isn't the above documentation complete? Are these elements new to reStructuredText?)
Related
In one of my Sphinx files, I have this :
.. _pyjnius:
Pyjnius
=======
When running on Android, a version of the `Pyjnius <https://pyjnius.readthedocs.io/en/stable/>`_
library is available. This allows advanced creators to call into the Android
libraries.
It seems to compile just how I want it to, but I get a warning saying that WARNING: Duplicate explicit target name: "pyjnius". I got to this issue, advising to end the link with two underscores rather than one, and that it's called an anonymous link. It's not the exact same problem: in the issue there's two links with the same name, and in my case there's only one link, but I tried the solution and it works.
What are the differences between `this <link>`_ and `that <link>`__, aka between anonymous and non-anonymous links ? What would happen if I convert all my external hyperlinks to the double-underscore syntax ?
What are the differences between (...) between anonymous and non-anonymous link
A reference name is created when you declare a hyperlink target. But if the target is anonymous the name isn't used to match the reference to its target. The following quote from the docs sums it up:
Anonymous Hyperlinks
The reference name of the reference is not used to match the reference to its target. Instead, the order of anonymous hyperlink references and targets within the document is significant: the first anonymous reference will link to the first anonymous target. The number of anonymous hyperlink references in a document must match the number of anonymous targets.
Now the second part of the question that was embedded in the same sentence:
What are the differences between `this <link>`_ and `that <link>`__
If you read the reStructuredText specification carefully, no clear example of the concise `Title <Link>`_ syntax is given, but it's an external hyperlink target (because the URL points to the exterior of your documentation). What happens is that the Title acts as the reference name for the target, hence the verbatim error: "Duplicate explicit target name".
Making the declaration of the hyperlink target anonymous by using the double underscore __ causes Title not to be used as the target name, thus there's no longer a duplicate target name because order of declaration is used to match the anonymous target to the link.
In conclusion:
and in my case there's only one link
Yes, but what the error message is saying is that there's a "Duplicate explicit target name" the problem is that Pyjnius is declared as a target once above the section, and again explicitly as the title (acting as target name) in the link using the shortened syntax.
Also note that the reference names (the target, or title) is normalized and thus case insensitive. Thus in your example the name Pyjnius <URL> ends up being normalized to pyjnius which is the same target name above the section.
Reference Names
case is normalized (all alphabetic characters are converted to lowercase).
(From https://groups.google.com/d/msg/bazel-discuss/HEpui0DLvnA/RzuwICDmBgAJ)
Forgive me if this has been asked and answered by the group/devs.
The list of "Declared include source" files is a component of the action key for C++ compiles.
This means that the addition of a header-extension file to srcs or hdrs of a cc_* target results in the invalidation of all compile actions which can see the declared list contents (in the hdrs case, transitively).
Can anyone explain how this could be necessary, when include pruning should be providing the minimal set of possible invalidation sources for a compile?
Reputation prevents me from commenting on your answer and the repost means that I don't own the question, but there is more to the problem than just a 're-validation':
Declared inclusion sources are transitively derived, resulting in action invalidation and reexecution (not simply re-validated, the definition of which is fuzzy at best for me) of all compiles in dependent targets.
The point of this post was to discuss (hence bazel-discuss) whether there is any way that previous compiled outputs could be affected, logistically, by adding (not discussing removal of) the definition of a header file, without changing any source related to the previous compilation. The inputs set, which would have been pruned to match the used header files, should (must) be an accurate enough depiction of the only possible triggers for action reexecution. The capacity of any compile to depend upon the newly added header is nil without further changes to the actual content of the input set of an action.
When the rule's definition changes (you add a file to srcs/hdrs), Bazel must assume that change may affect the compilation result, even if none of the other files changed. (For example you just added a header that was missing before.)
If you rebuild the target Bazel reruns the compilation action. If the output of that (the object file) is the same as the last time Bazel ran the action, it's going to re-validate downstream actions without re-executing them.
I've got an iOS framework that has a dependency on the (presumably Google maintained) pod called '!ProtoCompiler'. In order to build my framework I'm going to need it in the sandbox. So, I have a genrule and can try to include it with
src = glob(['Pods/!ProtoCompiler/**/*']) but I get the following error:
ERROR: BUILD:2:1: //Foo:framework-debug: invalid label 'Pods/!ProtoCompiler/google/protobuf/any.proto' in element 1118 of attribute 'srcs' in 'genrule' rule: invalid target name 'Pods/!ProtoCompiler/google/protobuf/any.proto': target names may not contain '!'.
As is, this seems like a total blocker for me using bazel to do this build. I don't have the ability to rename the pod directory as far as I can tell. As far as I can tell, the ! prohibition is supposed to be for target labels, is there any way I can specify that this is just a file, not a label? Or are those two concepts completely melded in bazel?
(Also, if I get this to work I'm worried about the fact that this produces a .framework directory and it seems like rules are expected to produces files only. Maybe I'll zip it up and then unzip it as part of the build of the test harness.)
As far as I can tell, the ! prohibition is supposed to be for target
labels, is there any way I can specify that this is just a file, not a
label? Or are those two concepts completely melded in bazel?
They are mostly molded.
Bazel associates a label with all source files in a package that appear in BUILD files, so that you can write srcs=["foo.cc", "//bar:baz.cc"] in a build rule and it'll work regardless of foo.cc and baz.cc being a source file, a generated file, or a build rule's name that produces files suitable for this particular srcs attribute.
That said you can of course have any file in the package, but if the name won't allow Bazel to derive a label from it, then you can't reference them in the BUILD file. Since glob is evaluated during loading and is expanded to a list of labels, using glob won't work around this limitation.
(...) it seems like rules are expected to produces files only. Maybe
I'll zip it up and then unzip it as part of the build of the test
harness.
Yes, that's the usual approach.
I have been reading topic regarding linux libraries
http://www.yolinux.com/TUTORIALS/LibraryArchives-StaticAndDynamic.html
it mentions:
"The benefit is that each and every object file need not be stated when linking because the developer can reference the individual library"
I am not following this statement. I wonder if someone could have a further explanation or an example please?
Thanks
It's not the best phrasing in the world, IIUC, and is a bit misleading. IMHO, instead of
The benefit is that each and every object file need not be stated when linking because the developer can reference the individual library
it should say
The benefit is that each and every object file need not be stated when linking because the developer can reference the entire library (as a named entity)
Basically, it means the following. In the absence of libraries, the author of what is now a library, could simply build a list of object files, like this:
a0.cpp -> a0.o
a1.cpp -> a1.o
...
and then she could write in the documentation "if you want functions x, y, and z", then you need to link with a3.o (because it contains x and z), a42.o (for y), but also a23.o, a15.o, and a72.o, because they contain necessary underlying parts.
This is of course unwieldy. A saner approach, as your link explains, is to create a single library from a state of common-purpose functions and classes. The instructions become "if you want the functionality of shooting up foo aliens, link with the foo_alien_shooting library".
I am using D2007 and am trying to document my source code, using the HelpInsight feature (provided since D2005). I am mainly interested in getting the HelpInsight tool-tips working. From various Web-surfing and experimentation I have found the following:
Using the triple slash (///) comment style works more often than the other documented comment styles. i.e.: {*! comment *} and {! comment }
The comments must precede the declaration that they are for. For most cases this will mean placing them in the interface section of the code. (The obvious exception is for types and functions that are not accessible from outside the current unit and are therefore declared in the implementation block.)
The first comment cannot be for a function. (i.e. it must be for a type - or at least it appears the parser must have seen the "type" keyword before the HelpInsight feature works)
Despite following these "rules", sometimes the Help-insight just doesn't find the comments I've written. One file does not produce the correct HelpInsight tool-tips, but if I include this file in a different dummy project, it works properly.
Does anyone have any other pointers / tricks for getting HelpInsight to work?
I have discovered another caveat (which in my case was what was "wrong")
It appears that the unit with the HelpInsight comments must be explicitly added to the project. It is not sufficient to simply have the unit in a path that is searched when compiling the project.
In other words, the unit must be included in the Project's .dpr / .dproj file. (Using the Project | "Add to Project" menu option)