Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Restructure Cookbook #404

Merged
merged 26 commits into from
Jul 10, 2018
Merged

Restructure Cookbook #404

merged 26 commits into from
Jul 10, 2018

Conversation

AndyGauge
Copy link
Collaborator

@AndyGauge AndyGauge commented Apr 26, 2018 •
edited
Loading

See it here

Fixes #375
Fixes #280
Fixes #139
Fixes #408
Fixes #421

link-checker ./book/
Summary: seen:5735 failed:0 unique:877

@AndyGauge AndyGauge changed the title Add algorithms Add algorithms, Command Line, Compression, Concurrency Apr 26, 2018
@aturon
Copy link

aturon commented May 1, 2018

btw, if you ever need reviewing, feel free to ping me on gitter!

@budziq
Copy link
Collaborator

budziq commented May 4, 2018

@AndyGauge this starts to look awesome.

Just few thoughts.

  • rendering on http://www.yetanother.site/rust-cookbook/ is a little wonky (missing icons etc. what version of mdbook did you use?)
  • there are some broken links and tables here and there. this leads me back to an idea to incorporate more lints to travis (link checker, markdown lint and aspell) so we do not need to spend any more time on rendering and link veriffication after each PR (especually major ones like this one)
  • do you have any thoughts where do we put tables (do webkeep them at all, split to smaller and smaller chunks)? The oroginal ones are not intended for this level of nesting and keeping them in sync will be even bigger chore than before. Maybe lets generate them on the fly?
  • I'm not sure if using {include} this much by hand will not make the maintenance and contribution more error prone (maybe we could just add each example to the SUMMARY.md directly or propose some changes to mdBook itself).

I'm really interested on your thoughts!

@AndyGauge
Copy link
Collaborator Author

@budziq Thank you for the kind words.

I'm using rust-lang/mdBook#682 as mdBook. It is a work in progress. The lastest version was before I incorporated relative path checking.

I haven't addressed the brokeness inside of the old categories. I"m trying to address dead links as I go, but this PR is far from finished. I expect to do a final manual pass once it is complete to address the broken tables and links. I am all for link verification post processing, but not blocking progress forward.

I'm hoping to generate tables on the fly eventually. If we keep mdBook I'm happy to write a TOC generator.

I'm hoping this much include syntax will be replaced eventually with a generator, but the idea is to break it up first. I envision a layout file, either TOML or YAML that generates everything.

Again, I do appreciate the thoughts. Last few days have been hacking away at mdBook and not the cookbook.

@budziq
Copy link
Collaborator

budziq commented May 5, 2018 •
edited
Loading

I tottally agree.

I'll try to find some time to add linkcheckers and linters to CI next week. It has been bugging me for some time already.

The layout file sounds very interesting! Please feel free to make a braindump with the details somewhere (possibly a separate issue in the repo might be a good place for discussion and getting help from contributors).

Sorry for closing the PR. Darn this mobile GitHub interface.

@budziq budziq closed this May 5, 2018
@budziq budziq reopened this May 5, 2018
@AndyGauge
Copy link
Collaborator Author

@budziq btw: https://github.com/Michael-F-Bryan/mdbook-linkcheck

@budziq
Copy link
Collaborator

budziq commented May 6, 2018

Very cool! Thanks!

@ludwigpacifici
Copy link
Contributor

FYI, #356 is open for checking links

@budziq
Copy link
Collaborator

budziq commented May 6, 2018

@ludwigpacifici Yep, I've opened it a long while ago and it has been nagging me since then ;) I hope to find some time to address it mid next week.

@AndyGauge AndyGauge changed the title Add algorithms, Command Line, Compression, Concurrency Add algorithms, Command Line, Compression, Concurrency, Cryptography, Data Structures, Development Tools May 9, 2018
@AndyGauge AndyGauge changed the title Add algorithms, Command Line, Compression, Concurrency, Cryptography, Data Structures, Development Tools Add Algorithms, Command Line, Compression, Concurrency, Cryptography, Data Structures, Development Tools May 9, 2018
@AndyGauge AndyGauge changed the title Add Algorithms, Command Line, Compression, Concurrency, Cryptography, Data Structures, Development Tools Add Algorithms, Command Line, Compression, Concurrency, Cryptography, Data Structures, Development Tools, Encoding, File System May 10, 2018
@AndyGauge AndyGauge changed the title Add Algorithms, Command Line, Compression, Concurrency, Cryptography, Data Structures, Development Tools, Encoding, File System Restructure Cookbook May 14, 2018
@AndyGauge
Copy link
Collaborator Author

I'm thinking about redoing the includes so I can release this on mdbook 0.1.7

This was referenced May 16, 2018
Closed
Closed
@AndyGauge AndyGauge mentioned this pull request May 16, 2018
Closed
@AndyGauge AndyGauge force-pushed the reorganize branch 2 times, most recently from 5fafd9f to 86fc014 Compare May 26, 2018 22:59
AndyGauge
AndyGauge commented Jun 5, 2018
View reviewed changes
src/web/clients/api/rate-limited.md Outdated
@@ -69,5 +69,5 @@ fn run() -> Result<()> {
# quick_main!(run);
```

[`hyper::header!`]: https://docs.rs/hyper/*/hyper/macro.header.html
[`hyper::header!`]: https://doc.servo.org/hyper/header/index.html#defining-custom-headers
Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This basically just references the 0.11 branch without breaking the wildcard rule. Not ideal, but #419 should solve it.

AndyGauge
AndyGauge commented Jun 5, 2018
View reviewed changes
src/web/clients/api/rest-head.md Outdated
@@ -2,7 +2,7 @@

[![reqwest-badge]][reqwest] [![cat-net-badge]][cat-net]

Query the [GitHub Users Endpoint](https://api.github.com/users) using a HEAD
Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It fails the link-checker, and didn't add any value. The url is hard coded in the code sample

@aturon
Copy link

aturon commented Jun 6, 2018 •
edited by AndyGauge
Loading

@AndyGauge This is a fantastic step forward! Just a few notes going through:

  • Concurrency: the "threads" vs "parallel tasks" is slightly confusing -- perhaps "explicit threads" vs "data parallelism" or something would be better?

  • Data structures

    • I'm not sure that lazy_static should go here -- at least for me, it's not super-connected to data structures. It's a really tricky one.
    • I didn't quite get the "custom" subcategory. Maybe just "bit manipulation"? (Are these subcategories also trying to map onto crates.io?)

  • Date/time

    • The "Duration" category seems to include more than just duration-related stuff, e.g. the "examine the date and time" example is not about durations.
    • The "convert a local time ..." example isn't about parsing/displaying, I think -- more like timezone calculation?

  • Development tools

    • I don't think "error handling" should go here; development tools are more about the development process itself (like debugging), whereas error handling is part of the actual application logic.

  • Encoding

    • The "strings" category feels a little too generic -- I'd have a hard time guessing what was in it. Similarly with "complex data types"
    • The relationship with "text processing" is a bit tricky, too

  • Web programming

    • I don't think "scraping web pages" should be a category -- better to break down into finer-grained pieces
    • Should use "URL" rather than "Uniform Resource Location" IMO; it's a ubiquitous acronym
    • For "Clients", the "Using APIs" category name is a bit unclear

@AndyGauge
Copy link
Collaborator Author

@aturon I had a tough time fitting all the recipes into categories--I may just need to create memory management and move lazy static there. Some of the series that I created were meant to divide the recipes in half to make them easier to digest. Sometimes the categories didn't fit the recipes. In Time/date, it probably makes sense to make a third series.

Can we petition crates.io to make an error handling category? Since we can't stuff it anywhere else in the cookbook I'll create a new root category for it.

@AndyGauge AndyGauge mentioned this pull request Jun 12, 2018
Closed
@AndyGauge
Copy link
Collaborator Author

@aturon I've worked through each of the comments, though some of them don't have great solutions. Did you want to review the updates?

@sandeep-datta
Copy link

Please consider the following changes ...

  1. Development tools does not seem to be the right place for Versioning. I'd rather see a separate category called change management (perhaps under development tools).

  2. Rename Encoding to Encoding / Decoding. Though technically correct placement of CSV processing and Structured data seems to be a little awkward. Perhaps create a separate category called Structured Data?

@AndyGauge
Copy link
Collaborator Author

@sandeep-datta Thank you for your review!

I actually do think Development tools is the right place for Versioning. I feel that change management might refer to state machines and not the development process. I'm wrong a lot though.

I certainly could see Encoding being renamed to Encoding / Decoding. I'll probably do that. We are trying to align the cookbook with the crates.io categories: https://crates.io/categories
I'd like to avoid creating extra categories.

@sandeep-datta
Copy link

I have never heard of change management being used in that sense but I think I should have said Configuration Management in the first place.

I'd like to avoid creating extra categories.

Well this is unfortunate but understandable. You may be already doing this but if I were you I'd make sure to look at the crates already using the chosen categories. If you were to look at the crates with "version" in their name you'd notice that most of them could have used a more appropriate category. I, for one, don't believe the list of categories on crates.io is complete by any means. But you be the judge.

Thanks again for all the hard work that you have put into this PR regardless of what you decide.

@AndyGauge
Fix broken links
29f4991 
support for additional linters (link-checker & aspell) (rust-lang-nursery#410)

* Added support for additional linters (html-proofer link checker)

- added additional test matrix item just for linters
- install and build mdbook only when needed to speedup CI
- reorganized the travis scripts

* Added spellchecking script from rust-book to CI

also fixed minor typos

* updated and moved serde_json links to propper position

* move link checking to link-checker

Move errors reorganize datetime add contributing instructions merge master

Renamed categories to avoid confusion fixed broken links

Use mdbook master branch until 0.1.8 releases

Revert "Use mdbook master branch until 0.1.8 releases"

This reverts commit a8dd8e3.
@AndyGauge AndyGauge merged commit 97dabe5 into rust-lang-nursery:master Jul 10, 2018
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers
No reviews
Assignees
No one assigned
Labels
None yet
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.
5 participants
@AndyGauge @aturon @budziq @ludwigpacifici @sandeep-datta