This converts it to be very similar to crates.mk, with a single list of
the documentation items creating all the necessary bits and pieces.
Changes include:
- rustdoc is used to render HTML & test standalone docs
- documentation building now obeys NO_REBUILD=1
- testing standalone docs now obeys NO_REBUILD=1
- L10N is slightly less broken (in particular, it shares dependencies
and code with the rest of the code)
- PDFs can be built for all documentation items, not just tutorial and
manual
- removes the obsolete & unused extract-tests.py script
- adjust the CSS for standalone docs to use the rustdoc syntax
highlighting
These are ancient. I removed a bunch of questions that are less relevant - or completely unrelevant, updated other entries, and removed things that are already better expressed elsewhere.
This has been a long time coming. Conditions in rust were initially envisioned
as being a good alternative to error code return pattern. The idea is that all
errors are fatal-by-default, and you can opt-in to handling the error by
registering an error handler.
While sounding nice, conditions ended up having some unforseen shortcomings:
* Actually handling an error has some very awkward syntax:
let mut result = None;
let mut answer = None;
io::io_error::cond.trap(|e| { result = Some(e) }).inside(|| {
answer = Some(some_io_operation());
});
match result {
Some(err) => { /* hit an I/O error */ }
None => {
let answer = answer.unwrap();
/* deal with the result of I/O */
}
}
This pattern can certainly use functions like io::result, but at its core
actually handling conditions is fairly difficult
* The "zero value" of a function is often confusing. One of the main ideas
behind using conditions was to change the signature of I/O functions. Instead
of read_be_u32() returning a result, it returned a u32. Errors were notified
via a condition, and if you caught the condition you understood that the "zero
value" returned is actually a garbage value. These zero values are often
difficult to understand, however.
One case of this is the read_bytes() function. The function takes an integer
length of the amount of bytes to read, and returns an array of that size. The
array may actually be shorter, however, if an error occurred.
Another case is fs::stat(). The theoretical "zero value" is a blank stat
struct, but it's a little awkward to create and return a zero'd out stat
struct on a call to stat().
In general, the return value of functions that can raise error are much more
natural when using a Result as opposed to an always-usable zero-value.
* Conditions impose a necessary runtime requirement on *all* I/O. In theory I/O
is as simple as calling read() and write(), but using conditions imposed the
restriction that a rust local task was required if you wanted to catch errors
with I/O. While certainly an surmountable difficulty, this was always a bit of
a thorn in the side of conditions.
* Functions raising conditions are not always clear that they are raising
conditions. This suffers a similar problem to exceptions where you don't
actually know whether a function raises a condition or not. The documentation
likely explains, but if someone retroactively adds a condition to a function
there's nothing forcing upstream users to acknowledge a new point of task
failure.
* Libaries using I/O are not guaranteed to correctly raise on conditions when an
error occurs. In developing various I/O libraries, it's much easier to just
return `None` from a read rather than raising an error. The silent contract of
"don't raise on EOF" was a little difficult to understand and threw a wrench
into the answer of the question "when do I raise a condition?"
Many of these difficulties can be overcome through documentation, examples, and
general practice. In the end, all of these difficulties added together ended up
being too overwhelming and improving various aspects didn't end up helping that
much.
A result-based I/O error handling strategy also has shortcomings, but the
cognitive burden is much smaller. The tooling necessary to make this strategy as
usable as conditions were is much smaller than the tooling necessary for
conditions.
Perhaps conditions may manifest themselves as a future entity, but for now
we're going to remove them from the standard library.
Closes#9795Closes#8968
Before this patch, if you wanted to add a crate to the build system you had to
change about 100 lines across 8 separate makefiles. This is highly error prone
and opaque to all but a few. This refactoring is targeted at consolidating this
effort so adding a new crate adds one line in one file in a way that everyone
can understand it.
Ensure configure creates doc/guides directory
Fix configure makefile and tests
Remove old guides dir and configure option, convert testing to guide
Remove ignored files
Fix submodule issue
prepend dir in makefile so that bor knows how to build the docs
S to uppercase
rustdoc:
- fix search-bar layout
doc: CSS:
- switch to native pandoc toc depth
- rm some dead code
- clamp width to be readable (we're not Wikipedia!)
- don't background-color titles, it's bloating
- make syntax-highlighting colors inline with rust-lang.org
- space indents
@alexcrichton
Since tutorial/manual files are stored on static.rust-lang.org, browsers
try to fetch the favicon from there while it should be retrieved from the
main domain.
Pandoc can create epub verions of the markdown files. Since the docs
are lengthy, epubs are handy to have around. Two rules to create epub
versions of the reference manual and the main tutorial are added here.
Signed-off-by: Noufal Ibrahim <noufal@nibrahim.net.in>
This modifies the command-line usage of rustdoc to intake its own JSON output as
well as a rust source file. This also alters the command line from
`rustdoc input file` to `rustdoc file` with the input/output formats specified
as -r and -w, respectively.
When using a JSON input, no passes or plugins are re-run over the json, instead
the output is generated directly from the JSON that was provided. Passes and
plugins are still run on rust source input, however.
Three things in this commit:
1. Actually build the rustpkg tutorial. I didn't know I needed this when
I first wrote it.
2. Link to it rather than the manual from the
tutorial.
3. Update the headers: most of them were one level too deeply
nested.
Removes old rustdoc, moves rustdoc_ng into its place instead (plus drops the _ng
suffix). Also shreds all reference to rustdoc_ng from the Makefile rules.
This large commit implements and `html` output option for rustdoc_ng. The
executable has been altered to be invoked as "rustdoc_ng html <crate>" and
it will dump everything into the local "doc" directory. JSON can still be
generated by changing 'html' to 'json'.
This also fixes a number of bugs in rustdoc_ng relating to comment stripping,
along with some other various issues that I found along the way.
The `make doc` command has been altered to generate the new documentation into
the `doc/ng/$(CRATE)` directories.
This commit add a new "docs-l10n" make target which uses po4a to:
* create .pot (PO templates) from markdown doc
* update templates and po for enabled languages
* generate translated markdown for completed (> 80%) translations
Currently, no language has been activated.
Signed-off-by: Luca Bruno <lucab@debian.org>
Most of our documentation requires both pandoc and node.js.
This simplifies the logic around those checks and fixes an
error when building without node.js but with pandoc.
Keywords are now listed in a plain text file. They're sorted in
column-major order and rendered as a texinfo multitable in rust.texi.
Fixes issue #1216.
Naturaldocs isn't really that great but it seems easier to get
something working than with doxygen, for which we would need to
convert rust code to something C++ish. We probably want to just
write a rustdoc utility at some point.
