It is possible to set both the favicon and the logo of the rustdoc for a crate by using:
#![doc(html_favicon_url = "<url_to>/favicon.ico")]
#![doc(html_logo_url = "<url_to>/logo.png")]
as documented here.
However I do not want to upload my logo publicly and would therefore like to automatically include these files in /target/doc and reference them from there.
Currently I have put the respective data urls (base64 encoded) into these fields and it works fine, but it enormously bloats the source file where these attributes are set.
I know I could just copy the images into target/doc after generating the documentation using a script and then reference them using the relative url, but I would like to avoid this, so that I can still generate the documentation using cargo doc.
Edit
The suggestion from the comment to set the --output flag of rustdoc using rustdocflags in .cargo/config.toml also did not work, because it leads to error: Option 'output' given more than once. Apart from that, it is not suited for me, because (at least as far as I understand) I can only give absolute paths there, whereas I would need a solution using relative paths for the images, because I have those images stored in a subdirectory of the cargo root directory, to allow for easy transfer to another system using git, etc.
Thanks to the latest comment from eggyal I finally figured out how to do this:
In my build.rs I copy the files to target/doc/:
fn main() {
// Copy the images to the output when generating documentation
println!("cargo:rerun-if-changed=assets/doc");
std::fs::copy("assets/doc/logo.ico", "target/doc/logo.ico").expect("Failed to copy crate favicon when building documentation.");
std::fs::copy("assets/doc/logo.png", "target/doc/logo.png").expect("Failed to copy crate logo when building documentation.");
}
and then I just had to make sure, to use an absolute path when referencing them, like so:
#![doc(html_favicon_url = "/logo.ico")]
#![doc(html_logo_url = "/logo.png")]
In general it would be better to read the CARGO_TARGET_DIR environment variable instead of hardcoding target/doc, but this is not yet available in build scripts.
Related
In my library I have few examples -- (normally) each one is represented by a single x<N>.rs file living in examples directory.
One example uses a .proto file -- this file needs to be compiled during build (of said example) and it's generated output is used by example itself.
I've tried this in my Cargo.toml:
[[example]]
name = "x1"
path = "examples/x1/main.rs"
build = "examples/x1/build.rs"
but build key gets ignored when I run cargo build --example x1
Is it possible to have example-specific build.rs file?
If not -- what is the correct way to deal with this situation?
Edit: I ended up processing that .proto file in crate's build.rs (even though it is not required to build that crate) and using artefacts in the example like this:
pub mod my_proto {
include!(concat!(env!("OUT_DIR"), "/my_proto.rs"));
}
This is not possible. This issue explains why, but in a nutshell build scripts are used for whole crate. So you could move your example into separate crate.
I am trying to customize the color of the LaTeX inline formula when using Sphinx documentation package, and html output.
The details:
I have a file called func.rst, which includes the following line:
Let :math:`x_{1}` be a binary variable.
which is rendered successfully into LaTeX in the documentation I created with Sphinx.
(I have 'sphinx.ext.imgmath' listed in extensions in conf.py)
My goal is to have x_{1} colored in red.
Things I tried:
Adding the color inside the formula:
Let :math:`\color{red}x_{1}` be a binary variable.
while also defining
latex_elements['preamble'] = '\usepackage{xcolor}'
in the conf.py file.
Trying to define all math output globally with:
latex_elements['preamble'] = r'''
\usepackage{xcolor}
\everymath{\color{red}}
\everydisplay{\color{red}}
'''
Needless to say, both (and many more less promising ideas) failed.
Copying over my answer on cross-posted question at tex.sx:
As you seem to be targeting html with math rendered as PNGs images (or SVGs), the current config value to configure isn't latex_elements, but imgmath_latex_preamble.
I tested since and it works.
For completeness sake, I am adding here the full solution. (THANKS jfbu!)
In conf.py I defined extensions = ['sphinx.ext.imgmath', <some_more_unrelated_stuff>]
Also in conf.py I defined
imgmath_latex_preamble=r'\usepackage{xcolor}'
(EDIT: in ooposed to what I previously wrote,there is no need to define in addition imgmath_latex="/usr/local/texlive/2017/bin/x86_64-darwin/latex" thanks jfbu again)
In the .rst file where I have the latex expression, I have
Let :math:`\color{red}x_{1}` be a binary variable.
In the terminal I run
make clean html
("make clean" is the sphinx's best friend)
And its working! wohoo!
I've got a very crude implementation working:
var screens = {
a: require('./../react_components/screens/a.jsx'),
b: require('./../react_components/screens/b.jsx'),
c: require('./../react_components/screens/c.jsx'),
d: require('./../react_components/screens/d.jsx'),
e: require('./../react_components/screens/e.jsx')
};
Which works fine, however, I'd like to make it a little more scalable, so that when I change a filename, or add a new file to the /screens folder, I don't really have to keep updating this list of require statements.
I'm using Browserify, so I do have a build step I can hook into if need be (this will be ran in the browser)
So for node/commonjs itself there are modules such as requireindex that will automate this kind of thing. However, the fact that these approaches determine the dependencies at runtime by looking at the filesystem defeats browserify's static analysis so I'm not aware of any of them that are browserify-compatible. Therefore, I'd suggest a code generation route where you use a module such as glob to discover the files you want to export, but then write out a full .js file with the exports all statically coded, and point browserify at that file, which you can regenerate every time during your build step.
If I have multiple .rs files in the src directory of a Cargo package, what are the rules for visibility, importing, etc.?
Currently, any extra (i.e. not the file that is explicitly identified as the source for the executable in Cargo.toml) files are ignored.
What do I need to do to fix this?
There is nothing special about Cargo at all in this way. It’s all the perfectly normal Rust module system. If Cargo will be compiling src/lib.rs, that’s more or less equivalent to having executed rustc --crate-type lib src/lib.rs (there are more command line arguments in practice, but that’s the basics of it).
Other files are then used with mod, use and so forth. Files are not automatically imported or anything like that. This part is not documented very clearly yet; a couple of things that show briefly how to achieve things are http://rustbyexample.com/mod/split.html and http://doc.rust-lang.org/reference.html#modules, but any non-trivial code base will use them and so you can pick just about any code base to look at for examples.
It's hard to say what you're getting tripped up on from the info you shared. Here are three seemingly trivial things that I still had to refer to the documentaton to figure out:
First of all,
mod foo;
looks like a declaration, but it without arguments it is actually something like an include. So you use the same keyword both for declaring and including modules, i.e. there is no using:: keyword.
Second, modules themselves can be public or private. If you didn't add a pub keyword both on the function in question AND on the containing module, that may be tripping you up.
pub mod foo {pub fn bar();}
Third, there seems to be an implicit module added at the top of every file. This is confusing; the reference manual talks about a strict separation between file paths and names, and the module paths in your code, but that abstraction seems to be leaky here.
Note, Rust is still pre-1.0 (0.12) at the time of writing, at the module system and file paths are relatively high level, so don't be surprised if what I said may already wrong by the time you read this.
Files are implicitly included from your rust code.
For instance, if a file src/foo.rs pointed by path in a [lib] or [[bin]] section of your Cargo.toml contains:
mod bar;
It tells cargo to build src/bar.rs too, and include it.
In this instance I'm using c with autoconf, but the question applies elsewhere.
I have a glade xml file that is needed at runtime, and I have to tell the application where it is. I'm using autoconf to define a variable in my code that points to the "specified prefix directory"/app-name/glade. But that only begins to work once the application is installed. What if I want to run the program before that point? Is there a standard way to determine what paths should be checked for application data?
Thanks
Thanks for the responses. To clarify, I don't need to know where the app data is installed (eg by searching in /usr,usr/local,etc etc), the configure script does that. The problem was more determining whether the app has been installed yet. I guess I'll just check in install location first, and if not then in "./src/foo.glade".
I dont think there's any standard way on how to locate such data.
I'd personally do it in a way that i'd have a list of paths and i'd locate if i can find the file from anyone of those and the list should containt the DATADIR+APPNAME defined from autoconf and CURRENTDIRECTORY+POSSIBLE_PREFIX where prefix might be some folder from your build root.
But in any case, dont forget to use those defines from autoconf for your data files, those make your software easier to package (like deb/rpm)
There is no prescription how this should be done in general, but Debian packagers usually installs the application data somewhere in /usr/share, /usr/lib, et cetera. They may also patch the software to make it read from appropriate locations. You can see the Debian policy for more information.
I can however say a few words how I do it. First, I don't expect to find the file in a single directory; I first create a list of directories that I iterate through in my wrapper around fopen(). This is the order in which I believe the file reading should be done:
current directory (obviously)
~/.program-name
$(datadir)/program-name
$(datadir) is a variable you can use in Makefile.am. Example:
AM_CPPFLAGS = $(ASSERT_FLAGS) $(DEBUG_FLAGS) $(SDLGFX_FLAGS) $(OPENGL_FLAGS) -DDESTDIRS=\"$(prefix):$(datadir)/:$(datadir)/program-name/\"
This of course depends on your output from configure and how your configure.ac looks like.
So, just make a wrapper that will iterate through the locations and get the data from those dirs. Something like a PATH variable, except you implement the iteration.
After writing this post, I noticed I need to clean up our implementation in this project, but it can serve as a nice start. Take a look at our Makefile.am for using $(datadir) and our util.cpp and util.h for a simple wrapper (yatc_fopen()). We also have yatc_find_file() in case some third-party library is doing the fopen()ing, such as SDL_image or libxml2.
If the program is installed globally:
/usr/share/app-name/glade.xml
If you want the program to work without being installed (i.e. just extract a tarball), put it in the program's directory.
I don't think there is a standard way of placing files. I build it into the program, and I don't limit it to one location.
It depends on how much customising of the config file is going to be required.
I start by constructing a list of default directories and work through them until I find an instance of glade.xml and stop looking, or not find it and exit with an error. Good candidates for the default list are /etc, /usr/share/app-name, /usr/local/etc.
If the file is designed to be customizable, before I look through the default directories, I have a list of user files and paths and work through them. If it doesn't find one of the user versions, then I look in the list of default directories. Good candidates for the user config files are ~/.glade.xml or ~/.app-name/glade.xml or ~/.app-name/.glade.xml.