[WIP] Curated Doc Refactoring #14245
Conversation
* Fixed strong/bold text (uses Arial for it with dark grey colour) * Added Source Code Pro for the code blocks. * Finally got a Pandoc, a normal Markdown library. * Finally got Rust syntax highlighting to work. * Styled the code.
* Converted all code blocks to the normal syntax * Reorganized the pages. * Added a "Next Up" section at the bottom of each page.
This seems quite unfortunate, depending on another language infrastructure. (AIUI, Ruby is somewhat less stable than e.g. Python, too?) It seems a Python generator would be more appropriate if we are going to use external tools. Another option is extending
It is only used for the optional step of compiling documentation to PDF; the HTML documentation (including tutorials etc.) is build just using |
I agree about it being unfortunate. I'm not a python person, so I naturally chose to go with a proven Ruby project.
Gotcha. I tried working with a Ruby gem (C + Ruby) for Markdown, but it didn't work correctly with Rust (it didn't detect Rust as a language). Curated docs would only really be built by contributors or those wanting to contribute where as rustdoc would be used by library authors and the like. Adding more dependencies is definitely a serious concern. |
|
Rustdoc can process standalone files, e.g. tutorial and so forth are processed by it currently. Nothing intrinsically wrong with Ruby. |
|
@adrientetar I thought about Jekyll, but before it's 2.0 release, it was purely a blogging platform. I'm waiting until Github Pages supports 2.0 (Last time I checked, they were working on it). |
|
rust-lang.org uses it, it’s not a blog. |
|
This looks pretty awesome, I'm excited to see where this goes! I am also concerned by the new dependencies brought in as part of this change. I don't want to require pandoc to build rust documentation, and what does the site generator buy us that we don't already have? We can add options to rustdoc to inject html at the start/end of files (which appears to be what the generator is doing), and we could style the existing markdown similarly. |
It does it already, @huonw implemented a pandoc (almost) drop-in replacement as part of his standalone Markdown processing PR. |
Yes, there's nothing particularly wrong with Ruby itself, but there are problems with adding new dependencies. |
@adrientetar Simple static sites works fine with Jekyll < 2.0, but it wasn't meant for extensive documentation or other focuses. I'm a little hesitant about adding more functionality to rustdoc. It seems too much like rebuilding the wheel with no real gains (other than squashing some dependencies). One solution would be to move to a Python system (like @huonw suggested) and use Sphinx for the curated docs, which I believe @chris-morgan has been advocating for it. There would be a few downsides:
Sphinx, however, is used by quite a lot of notable projects, including Julia's docs. It also offers the ability to generate PDF, HTML and ePub bundles without much pain. It also does syntax highlighting to Pygments, which supports Rust, so that's all good. The only thing that needs to change is the validation (which currently works on Markdown code blocks), but Sphinx apparently has code validation built-in. I'm not sure if that allows it to pipe each code block to a specific process or what not, but I'll look into it. Thoughts @alexcrichton @huonw or anyone else? |
|
We will be rebuilding the wheel in some cases, but the wheel that we're rebuilding is normally quite simple. For example, markdown => html was a small wheel rebuilt via the glue we have to hoedown, but it was well worth our time because now we're able to parse, extract, colorize, and test code examples in rustdoc itself. I view this as pulling in more than just a dependency, but also adding a whole new system that has to be maintained across all our bots, all contributors checkouts, etc. I've found that everything is much much simpler if we're willing to write a bit more code to implement simple things like markdown => html generation (and others). I would prefer to explore how to leverage what rustdoc already gives (injection at the header and footer of every page) before exploring any solution written in either python or ruby. We shouldn't have a need for a full-blown static site generator, we're just serving up some simple documentation. We're also not moving to Sphinx at this time, we're sticking with Markdown. |
|
@alexcrichton Gotcha. I agree then. I'll start integrating this stuff into rustdoc. |
From this PR it seems like you are adding index.html to every file, testing code blocks and syntax highlighting code. |
|
Closing this PR for now until I'm finished. |
thehydroimpulse
changed the title
Disable pattern type mismatches again We have too many false mismatches at the moment for these to be enabled cc rust-lang/rust-analyzer#14222
It seems as if `#![feature(binary_heap_into_iter_sorted)]` is not required anymore. changelog: none
This isn't ready for prime time yet, feedback is super important in areas like this, so that's what I'm looking for.
This is in relation to the Splitting the Docs thread I posted to the mailing list.
In summary, this will replace the current curated documentation with a more appropriate system. This introduces nanoc as the static site generator. There's no particularly huge reasons why nanoc was chosen, it works pretty well, and Github uses it for it's developer documentation.
There's two parts to this system:
Ensuring that the code blocks are legitimate Rust code is super important. The validator takes a directory as an argument
./validator ./dirand walks the files and validates them. It's currently intended for Markdown files, but it can be extended for other uses. That's all it does. It's still somewhat rough and not perfect (could use some parallelism to speed it up).You can also view a live version.
The ultimate goal is to provide a better user experience for new comers. Currently, we have a few problems:
Thus, turning to a more extensible platform would allow us to control the user through each step of the process. I'm turning to the Julia docs as an example.
Dependencies
Unfortunately (perhaps delegation is a good thing), new dependencies emerge.
Note: This new system is not tied to Rust in any way. Meaning, doing
make checkor running the standard commands does not initiate the new docs. They're isolated for the time being (and because I haven't made my strides into the wonderlands of Rust's makefiles).Todo
introduction,syntax, etc...).Overall, I'm pretty content with the simplistic design, similar to how the current docs are. It's not perfect yet, but the typography feels solid and doesn't require external fonts.