Stream: wg-traits

Topic: high-level docs


tmandry (Oct 16 2018 at 01:43, on Zulip):

I wrote down some ideas I had in this issue comment
cc @nikomatsakis @Sunjay Varma

tmandry (Oct 16 2018 at 01:44, on Zulip):

although @nikomatsakis you may have had more developed ideas

Sunjay Varma (Oct 16 2018 at 02:15, on Zulip):

I replied to your issue comment :)

Sunjay Varma (Oct 16 2018 at 02:15, on Zulip):

Great ideas! :D

scalexm (Oct 19 2018 at 13:41, on Zulip):

@nikomatsakis @tmandry @Sunjay Varma I finished writing the implied bounds chapter in the rustc guide https://github.com/rust-lang-nursery/rustc-guide/pull/212 , please tell me if it's understandable

nikomatsakis (Oct 19 2018 at 13:46, on Zulip):

I'm at Rust Belt Rust today, btw.

nikomatsakis (Oct 19 2018 at 13:46, on Zulip):

btw @tmandry (and/or @Sunjay Varma) — shall we schedule a slot next week to chat about high-level docs?

Sunjay Varma (Oct 19 2018 at 15:06, on Zulip):

@nikomatsakis Yes. Monday or Friday would be best for me. Monday at 2:30 EST or Friday anytime after 2 pm EST

Sunjay Varma (Oct 19 2018 at 15:06, on Zulip):

Next week is particularly busy because of interviews, so if neither of those work I should have more time the week after that. :blush:

tmandry (Oct 22 2018 at 01:12, on Zulip):

@scalexm Looks good! I started reviewing but github is screwed up right now and I can't post anything :expressionless:

tmandry (Oct 26 2018 at 16:07, on Zulip):

btw @scalexm @nikomatsakis @Sunjay Varma I don't know if you saw https://github.com/rust-lang-nursery/rustc-guide/pull/219

scalexm (Oct 26 2018 at 16:44, on Zulip):

@tmandry ah very nice

Sunjay Varma (Oct 26 2018 at 17:23, on Zulip):

@tmandry thanks for working on that! Looks great!

nikomatsakis (Oct 26 2018 at 17:33, on Zulip):

@tmandry I did not yet, but i'm excited to read it

tmandry (Oct 26 2018 at 17:33, on Zulip):

it's mostly light edits and reorganizing, not much new content yet :)

tmandry (Oct 26 2018 at 17:34, on Zulip):

so @nikomatsakis and I spoke at RBR last week, and I put together a list of "action items" that I think covers what we talked about

tmandry (Oct 26 2018 at 17:35, on Zulip):

how about if I post those on the issue and we can tackle it "quest-style"

nikomatsakis (Oct 26 2018 at 18:32, on Zulip):

sounds great!

tmandry (Oct 26 2018 at 18:39, on Zulip):

@nikomatsakis ok, I posted them here, please take a look and let me know if anything seems off

nikomatsakis (Oct 26 2018 at 18:40, on Zulip):

@tmandry ps if you do the nit that @scalexm recommended, I can merge your PR

tmandry (Oct 26 2018 at 18:43, on Zulip):

@nikomatsakis pushed

nikomatsakis (Oct 26 2018 at 19:07, on Zulip):

merged

tmandry (Oct 29 2018 at 19:11, on Zulip):

we discussed the idea of linking to code more from the rustc guide, as a way of making things "more concrete"

tmandry (Oct 29 2018 at 19:11, on Zulip):

..one problem is that we would link to old code (github permalinks can keep broken links from happening, but not from going stale)

tmandry (Oct 29 2018 at 19:12, on Zulip):

thankfully, we have nightly-rustc docs!

tmandry (Oct 29 2018 at 19:13, on Zulip):

I propose we start linking to these throughout rustc-guide..

tmandry (Oct 29 2018 at 19:13, on Zulip):

it would be nice to have them for chalk, too (--document-private-items needs to be turned on)

Sunjay Varma (Oct 29 2018 at 19:18, on Zulip):

Do the private items in chalk have sufficient documentation?

Sunjay Varma (Oct 29 2018 at 19:18, on Zulip):

That might also be a good place for improvement

tmandry (Oct 29 2018 at 19:18, on Zulip):

not yet :)

Sunjay Varma (Oct 29 2018 at 19:19, on Zulip):

Making the code more readable with some comments

Sunjay Varma (Oct 29 2018 at 19:19, on Zulip):

:D

tmandry (Oct 29 2018 at 19:19, on Zulip):

agreed

tmandry (Oct 29 2018 at 19:19, on Zulip):

well, some of it is pretty well documented iirc

tmandry (Oct 29 2018 at 19:20, on Zulip):

in any case, if we get in the habit of making these links

tmandry (Oct 29 2018 at 19:20, on Zulip):

hopefully it will become clear when there are improvements to be made

tmandry (Oct 29 2018 at 19:29, on Zulip):

..so, hosting docs with --document-private-items might be difficult

tmandry (Oct 29 2018 at 19:29, on Zulip):

the easiest way I can see is using GitLab CI

Sunjay Varma (Oct 29 2018 at 19:30, on Zulip):

Is it possible to do during the existing Travis build?

tmandry (Oct 29 2018 at 19:31, on Zulip):

building is possible, but I'm not sure where to host

Sunjay Varma (Oct 29 2018 at 19:31, on Zulip):

On GitHub pages?

Sunjay Varma (Oct 29 2018 at 19:31, on Zulip):

gh-pages branch of the chalk repo?

tmandry (Oct 29 2018 at 19:32, on Zulip):

I looked at that, but it seems that it forces you to use Jekyll. do you know if you can stick raw HTML in there?

Sunjay Varma (Oct 29 2018 at 19:33, on Zulip):

Yes. You can actually use it without having to interact with Jekyll at all

Sunjay Varma (Oct 29 2018 at 19:33, on Zulip):

That's just if you need to do any fancy stuff

tmandry (Oct 29 2018 at 19:33, on Zulip):

oh okay, my bad. we can do that then

Sunjay Varma (Oct 29 2018 at 19:34, on Zulip):

https://github.com/sunjay/maze-generator/tree/gh-pages?files=1

Sunjay Varma (Oct 29 2018 at 19:34, on Zulip):

A really old repo of mine with just some simple HTML and CSS

Sunjay Varma (Oct 29 2018 at 19:34, on Zulip):

No need to interact with Jekyll at all :)

tmandry (Oct 29 2018 at 19:50, on Zulip):

@nikomatsakis what do you think about putting chalk private docs in gh-pages?

tmandry (Oct 29 2018 at 19:50, on Zulip):

also, do you have access to Travis? I can send you the instructions for adding an access token

nikomatsakis (Oct 29 2018 at 20:00, on Zulip):

thankfully, we have nightly-rustc docs!

yep, this is what I tend to link to

nikomatsakis (Oct 29 2018 at 20:00, on Zulip):

what do you think about putting chalk private docs in gh-pages?

sounds good to me

nikomatsakis (Oct 29 2018 at 20:00, on Zulip):

also, do you have access to Travis? I can send you the instructions for adding an access token

I do

nikomatsakis (Oct 29 2018 at 20:01, on Zulip):

I can figure it out, but I would love it if you are able to send me what to do :) I always have to go figure this stuff out again afresh and I hate doing it

tmandry (Oct 29 2018 at 20:01, on Zulip):

no problem, give me one second :)

tmandry (Oct 29 2018 at 20:09, on Zulip):

@nikomatsakis sent you PMs

tmandry (Oct 29 2018 at 20:13, on Zulip):

hmm, do we want to generate docs for dependencies?

tmandry (Oct 29 2018 at 20:14, on Zulip):

to start I'm leaning toward no, but if anyone thinks it might be helpful we can add them

Sunjay Varma (Oct 29 2018 at 20:15, on Zulip):

I believe there is something that docs.rs does that allows it to link externally to outside crates

Sunjay Varma (Oct 29 2018 at 20:15, on Zulip):

Helps them de-dupe the docs

Sunjay Varma (Oct 29 2018 at 20:15, on Zulip):

I am not sure how it works though

Sunjay Varma (Oct 29 2018 at 20:15, on Zulip):

Just that it is probably possible

Sunjay Varma (Oct 29 2018 at 20:15, on Zulip):

We also apparently do that for std docs

Sunjay Varma (Oct 29 2018 at 20:16, on Zulip):

Those are not generated with every crate

tmandry (Oct 29 2018 at 20:20, on Zulip):

@Sunjay Varma okay, I don't see anything in the cargo doc help, but I'm sure there is a way :)

Sunjay Varma (Oct 29 2018 at 20:21, on Zulip):

I asked on Twitter: https://twitter.com/Sunjay03/status/1057004483220107266

Sunjay Varma (Oct 29 2018 at 20:21, on Zulip):

Hopefully someone knows :)

Sunjay Varma (Oct 29 2018 at 20:28, on Zulip):

https://twitter.com/QuietMisdreavus/status/1057005767222534150

Sunjay Varma (Oct 29 2018 at 20:29, on Zulip):

So basically it's possible, but not very pretty

Sunjay Varma (Oct 29 2018 at 20:29, on Zulip):

We could potentially just live with the default behaviour of cargo doc

Sunjay Varma (Oct 29 2018 at 20:29, on Zulip):

It's not too bad

tmandry (Oct 29 2018 at 20:35, on Zulip):

I didn't see any examples in the docs where it linked to another crate, locally

tmandry (Oct 29 2018 at 20:35, on Zulip):

we can always add the deps later, if needed..?

Sunjay Varma (Oct 29 2018 at 20:36, on Zulip):

Well any types we use from an external crate will be linked

Sunjay Varma (Oct 29 2018 at 20:36, on Zulip):

Are you explicitly using the --no-deps flag?

Sunjay Varma (Oct 29 2018 at 20:36, on Zulip):

If you leave that off cargo will automatically generate the docs for the deps anyway

Sunjay Varma (Oct 29 2018 at 20:36, on Zulip):

so you can just use that

tmandry (Oct 29 2018 at 20:37, on Zulip):

yeah I tried with/without

tmandry (Oct 29 2018 at 20:37, on Zulip):

I was just trying to avoid bloat :) I have no problem with leaving them in though

Sunjay Varma (Oct 29 2018 at 20:39, on Zulip):

It will increase the build times, but I think that's a small price to pay. If you're really feeling up for some experimentation you can try using the travis cache to speed things up. You'd have to add the target/doc directory to the configuration. See the bottom of this blog post: https://levans.fr/rust_travis_cache.html

Sunjay Varma (Oct 29 2018 at 20:39, on Zulip):

I would consider that optional though for a first pass at getting this working :)

tmandry (Oct 29 2018 at 22:57, on Zulip):

okay, docs are live at https://rust-lang-nursery.github.io/chalk/doc/chalk/index.html

Jake Goulding (Oct 29 2018 at 23:23, on Zulip):

It looks like some of the documentation wasn't rendered :smiling_imp: (obviously that's the reason some is missing, couldn't be that it wasn't documented to start with)

Jake Goulding (Oct 29 2018 at 23:24, on Zulip):

But for real, I appreciate that, a lot of times, good Rust code is fairly readable without docs.

Jake Goulding (Oct 29 2018 at 23:25, on Zulip):

Although this version of rustdoc has an interesting rendering bug:

pasted image

Jake Goulding (Oct 29 2018 at 23:33, on Zulip):

I have mentioned this for the unsafe guidelines, but I'd also heartily recommend adding a glossary of some sort. It could just be a section of the crates docs or maybe the rustc guide. It doesn't need to be all-encompassing, but having links to things would be a great start.

Jake Goulding (Oct 29 2018 at 23:34, on Zulip):

For example, what is a universe (no need to answer here, add it to the glossary and point me to that :wink:)

Sunjay Varma (Oct 29 2018 at 23:36, on Zulip):

https://rust-lang-nursery.github.io/rustc-guide/borrow_check/region_inference.html#what-is-a-universe

Sunjay Varma (Oct 29 2018 at 23:36, on Zulip):

We should definitely have a glossary!

Jake Goulding (Oct 29 2018 at 23:57, on Zulip):

/me reads the link

Jake Goulding (Oct 29 2018 at 23:57, on Zulip):

... and maybe an ELI5 glossary

tmandry (Oct 30 2018 at 00:21, on Zulip):

@Jake Goulding yes, agreed. a full glossary is on the to do list

tmandry (Oct 30 2018 at 00:22, on Zulip):

there is a glossary in the chalk repo, but could probably use some updates and/or additions

Jake Goulding (Oct 30 2018 at 00:35, on Zulip):

well then, consider my request to now be to combine the glossaria and then add a link to the final result from the crate docs ;-)

Jake Goulding (Oct 30 2018 at 00:36, on Zulip):

This one seems to be about what I was looking for, though!

nikomatsakis (Oct 30 2018 at 17:16, on Zulip):

@tmandry looking at your outline, one thing I am not sure about is how/when to talk about "canonicalization". In some sense, the current layering is good, but then canonicalization is also used in the SLG solver implementation internally in order to find the "canonical table" for a given goal etc

nikomatsakis (Oct 30 2018 at 17:16, on Zulip):

so I think maybe it wants to move to 2.iii

tmandry (Oct 30 2018 at 17:20, on Zulip):

@nikomatsakis ok, do you think it makes sense then to leave "Canonical queries" out as section 3? with a link back to canonicalization in 2.iii

nikomatsakis (Oct 30 2018 at 17:20, on Zulip):

hmm

nikomatsakis (Oct 30 2018 at 17:20, on Zulip):

I wonder if there are some parts that will be specific to rustc

nikomatsakis (Oct 30 2018 at 17:21, on Zulip):

what did you envision going in that section?

nikomatsakis (Oct 30 2018 at 17:21, on Zulip):

(it occurs to me that there is some more content that could go after the SLG solver, e.g., aggregation and truncation)

tmandry (Oct 30 2018 at 17:21, on Zulip):

which section?

tmandry (Oct 30 2018 at 17:21, on Zulip):

I'm not planning on changing canonicalization or canonical queries at the moment

tmandry (Oct 30 2018 at 17:22, on Zulip):

for the SLG solver I was going to start with your blog post / the chalk-engine README

nikomatsakis (Oct 30 2018 at 17:23, on Zulip):

ok I was thinking that maybe canonicalization can just move and not be its own high-level bullet point

tmandry (Oct 30 2018 at 17:24, on Zulip):

yeah, it seems like it makes sense to put it under 2 somewhere

tmandry (Oct 30 2018 at 17:25, on Zulip):

whether it's part of 2.iii is just a matter of how we want to break it up

tmandry (Oct 30 2018 at 17:26, on Zulip):

this would be the "general operation" of canonicalization, and canonical queries which are rustc-specific can go in 3

tmandry (Oct 30 2018 at 17:26, on Zulip):

..which may grow to encompass more rustc-specific stuff, one day

tmandry (Oct 30 2018 at 17:31, on Zulip):

/me curses self for using roman numerals

tmandry (Oct 30 2018 at 17:32, on Zulip):

@nikomatsakis I updated the outline

tmandry (Nov 02 2018 at 19:19, on Zulip):

@nikomatsakis will you proofread https://github.com/rust-lang-nursery/rustc-guide/pull/222 and possibly https://github.com/rust-lang-nursery/rustc-guide/pull/223 ?

nikomatsakis (Nov 02 2018 at 20:08, on Zulip):

I was doing that now

nikomatsakis (Nov 02 2018 at 20:10, on Zulip):

@tmandry where did we publish the chalk rustdocs again?

tmandry (Nov 02 2018 at 20:11, on Zulip):

@nikomatsakis https://rust-lang-nursery.github.io/chalk/doc/chalk

Alexander Regueiro (Nov 02 2018 at 20:21, on Zulip):

@nikomatsakis fixed the nit you brought up. I'll be around if you have any more requests before you r+ though (or alternatively feel free to make the commit yourself directly.)

nikomatsakis (Nov 02 2018 at 20:32, on Zulip):

@scalexm I left a few nits on https://github.com/rust-lang-nursery/rustc-guide/pull/222, would you rather fix them? Nothing major so I am also ok with landing and revisiting later

scalexm (Nov 02 2018 at 20:32, on Zulip):

@nikomatsakis ok I'll fix them

scalexm (Nov 02 2018 at 20:51, on Zulip):

@nikomatsakis done

tmandry (Nov 20 2018 at 05:38, on Zulip):

@nikomatsakis not sure if you wanted to review https://github.com/rust-lang-nursery/rustc-guide/pull/228 (you wrote most of it :) )

nikomatsakis (Nov 20 2018 at 19:08, on Zulip):

@nikomatsakis not sure if you wanted to review https://github.com/rust-lang-nursery/rustc-guide/pull/228 (you wrote most of it :) )

merged

Last update: Nov 12 2019 at 16:00UTC