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.

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

cargo doc: add option to document private types #1520

Open
SimonSapin opened this Issue Apr 13, 2015 · 21 comments

Comments

Projects
None yet
@SimonSapin
Contributor

SimonSapin commented Apr 13, 2015

rustdoc can include private items in the generated documentation: rust-lang/rust#15347 (comment)
This is triggered by passing --no-defaults --passes "collapse-docs" --passes "unindent-comments" to it. This has two issues:

  • It’s very hard to discover
  • Cargo does not allow giving arbitrary parameters to rustdoc: #331

Could Cargo do this itself e.g. when [lib] doc-private = true is set in Cargo.toml?

@dbrgn

This comment has been minimized.

Show comment
Hide comment
@dbrgn

dbrgn May 20, 2015

Contributor

I'd prefer a cargo doc parameter instead of (or in addition to) the Cargo.toml version. Many times you want cargo doc to build the "official" documentation, but would like to use cargo doc --include-private to generate a version for yourself or other library devs.

Contributor

dbrgn commented May 20, 2015

I'd prefer a cargo doc parameter instead of (or in addition to) the Cargo.toml version. Many times you want cargo doc to build the "official" documentation, but would like to use cargo doc --include-private to generate a version for yourself or other library devs.

@majkcramer

This comment has been minimized.

Show comment
Hide comment
@majkcramer

majkcramer commented May 23, 2015

+1

@LukasKalbertodt

This comment has been minimized.

Show comment
Hide comment
@LukasKalbertodt

LukasKalbertodt Aug 27, 2015

Contributor

+1

Another idea: Would it make sense to enable doc generation of private types for non-library projects by default?

If you're developing a library, the docs are mainly for your users and those are not interested in private stuff. To not generate docs for private types by default makes sense here. Developers of the library can use the command line parameter to generate docs with private types for their use.

If you're developing a program (non-library), what are docs for then? Normal "users" of the program don't care about the source code and the documentation. So the docs are probably mainly for developers. It makes sense to generate docs for private types here. IMO.

Contributor

LukasKalbertodt commented Aug 27, 2015

+1

Another idea: Would it make sense to enable doc generation of private types for non-library projects by default?

If you're developing a library, the docs are mainly for your users and those are not interested in private stuff. To not generate docs for private types by default makes sense here. Developers of the library can use the command line parameter to generate docs with private types for their use.

If you're developing a program (non-library), what are docs for then? Normal "users" of the program don't care about the source code and the documentation. So the docs are probably mainly for developers. It makes sense to generate docs for private types here. IMO.

@ssokolow

This comment has been minimized.

Show comment
Hide comment
@ssokolow

ssokolow Aug 27, 2015

@LukasKalbertodt

I have to agree. In my Python projects, I use ePyDoc to get a structured overview of my code when I'm returning from working on something else and the Rust book didn't even mention that private types wouldn't get documented.

Since my first project was an application project, that led me to get really frustrated because I thought it was something that was supposed to work and, thus, something I'd done wrong.

ssokolow commented Aug 27, 2015

@LukasKalbertodt

I have to agree. In my Python projects, I use ePyDoc to get a structured overview of my code when I'm returning from working on something else and the Rust book didn't even mention that private types wouldn't get documented.

Since my first project was an application project, that led me to get really frustrated because I thought it was something that was supposed to work and, thus, something I'd done wrong.

@dbrgn

This comment has been minimized.

Show comment
Hide comment
@dbrgn
Contributor

dbrgn commented Aug 27, 2015

@SimonSapin

This comment has been minimized.

Show comment
Hide comment
@SimonSapin

SimonSapin Aug 27, 2015

Contributor

Cargo does not allow giving arbitrary parameters to rustdoc: #331

In Servo we’ve worked around that by calling Cargo with a RUSTDOC environment variable set to the name of this wrapper script:

#!/bin/sh
rustdoc --no-defaults --passes collapse-docs --passes unindent-comments "$@"

servo/servo#6655, servo/servo#6668

Contributor

SimonSapin commented Aug 27, 2015

Cargo does not allow giving arbitrary parameters to rustdoc: #331

In Servo we’ve worked around that by calling Cargo with a RUSTDOC environment variable set to the name of this wrapper script:

#!/bin/sh
rustdoc --no-defaults --passes collapse-docs --passes unindent-comments "$@"

servo/servo#6655, servo/servo#6668

@ticki

This comment has been minimized.

Show comment
Hide comment
@ticki

ticki Feb 6, 2016

What is the state of this?

ticki commented Feb 6, 2016

What is the state of this?

@jonas-schievink

This comment has been minimized.

Show comment
Hide comment
@jonas-schievink

jonas-schievink Feb 6, 2016

I think cargo rustdoc allows this and more, so the only thing left is to enable private docs for binaries by default, as per @LukasKalbertodt's suggestion (that's probably a different issue, though!). Oh, and this still is quite hard to discover.

jonas-schievink commented Feb 6, 2016

I think cargo rustdoc allows this and more, so the only thing left is to enable private docs for binaries by default, as per @LukasKalbertodt's suggestion (that's probably a different issue, though!). Oh, and this still is quite hard to discover.

@reem

This comment has been minimized.

Show comment
Hide comment
@reem

reem Mar 4, 2016

I also would like this for hosting internal documentation of libraries for people who want to develop those libraries vs. users of those libraries.

reem commented Mar 4, 2016

I also would like this for hosting internal documentation of libraries for people who want to develop those libraries vs. users of those libraries.

@dbrgn

This comment has been minimized.

Show comment
Hide comment
@dbrgn

dbrgn Mar 10, 2016

Contributor

For the record, this seems to work:

$ cargo rustdoc -- --no-defaults --passes "collapse-docs" --passes "unindent-comments"
Contributor

dbrgn commented Mar 10, 2016

For the record, this seems to work:

$ cargo rustdoc -- --no-defaults --passes "collapse-docs" --passes "unindent-comments"
@solson

This comment has been minimized.

Show comment
Hide comment
@solson

solson Apr 8, 2016

Member

Based on the newest servo rustdoc-with-private script and the cargo rustdoc command I tend to run cargo rustdoc --open -- --no-defaults --passes collapse-docs --passes unindent-comments --passes strip-priv-imports.

I think there should be first-class support for private docs during development, so I can do something like cargo doc --private --open or cargo doc --dev --open instead of writing a shell alias. Another aspect of this first-class support would be rustdoc showing which items are private and public, but that's outside the scope of this cargo issue.

EDIT: Well, rustdoc already shows pub in the page for an item, but not in links to that item or in lists of methods, so it could be a bit better.

Member

solson commented Apr 8, 2016

Based on the newest servo rustdoc-with-private script and the cargo rustdoc command I tend to run cargo rustdoc --open -- --no-defaults --passes collapse-docs --passes unindent-comments --passes strip-priv-imports.

I think there should be first-class support for private docs during development, so I can do something like cargo doc --private --open or cargo doc --dev --open instead of writing a shell alias. Another aspect of this first-class support would be rustdoc showing which items are private and public, but that's outside the scope of this cargo issue.

EDIT: Well, rustdoc already shows pub in the page for an item, but not in links to that item or in lists of methods, so it could be a bit better.

@durka

This comment has been minimized.

Show comment
Hide comment
@durka

durka Aug 17, 2016

Contributor

How to do this is a fairly common question and though cargo rustdoc makes it tractable (I used to do this) the long incantation (even longer now with --passes strip-private-imports) is hardly welcoming to newcomers. I think this is an important option to add. 👍 👍

Would a PR be accepted or is an RFC required?

Contributor

durka commented Aug 17, 2016

How to do this is a fairly common question and though cargo rustdoc makes it tractable (I used to do this) the long incantation (even longer now with --passes strip-private-imports) is hardly welcoming to newcomers. I think this is an important option to add. 👍 👍

Would a PR be accepted or is an RFC required?

@kelseasy

This comment has been minimized.

Show comment
Hide comment
@kelseasy

kelseasy Nov 30, 2016

I would love to be able to do cargo doc --passes [...]. I'd be willing to work on this, through an RFC or a PR, whichever makes the most sense.

kelseasy commented Nov 30, 2016

I would love to be able to do cargo doc --passes [...]. I'd be willing to work on this, through an RFC or a PR, whichever makes the most sense.

@NfNitLoop

This comment has been minimized.

Show comment
Hide comment
@NfNitLoop

NfNitLoop Mar 30, 2017

I just wanted this feature again today. Was showing off rustdoc for a binary crate I'm working on, but it's pretty unimpressive since none of its (sub)modules is public and I couldn't quickly remember the invocation to make cargo docs do what I wanted.

Add my name to the list of folks who would be happy to look into implementing this. :)

NfNitLoop commented Mar 30, 2017

I just wanted this feature again today. Was showing off rustdoc for a binary crate I'm working on, but it's pretty unimpressive since none of its (sub)modules is public and I couldn't quickly remember the invocation to make cargo docs do what I wanted.

Add my name to the list of folks who would be happy to look into implementing this. :)

@mbr

This comment has been minimized.

Show comment
Hide comment
@mbr

mbr Apr 12, 2017

Please make this more accessible, I've been missing this feature countless times.

mbr commented Apr 12, 2017

Please make this more accessible, I've been missing this feature countless times.

@hdevalence

This comment has been minimized.

Show comment
Hide comment
@hdevalence

hdevalence Jun 27, 2017

I'd also really like this feature. I also think it would be great to have a profile for "all docs", so that sites like docs.rs can build both "external" and "internal" docs -- this would mean that the internal docs are also linkable, which local doc builds aren't.

hdevalence commented Jun 27, 2017

I'd also really like this feature. I also think it would be great to have a profile for "all docs", so that sites like docs.rs can build both "external" and "internal" docs -- this would mean that the internal docs are also linkable, which local doc builds aren't.

@pjmlp

This comment has been minimized.

Show comment
Hide comment
@pjmlp

pjmlp Jul 8, 2017

I would also join my voice to those complaining for lack of support.

Thanks to solson now I have a bash script calling into cargo, but it took me a while to find out how this is at all possible.

pjmlp commented Jul 8, 2017

I would also join my voice to those complaining for lack of support.

Thanks to solson now I have a bash script calling into cargo, but it took me a while to find out how this is at all possible.

@LinearZoetrope

This comment has been minimized.

Show comment
Hide comment
@LinearZoetrope

LinearZoetrope Sep 20, 2017

I feel like it would be nice to optionally have cargo doc generate both developer and public documentation. Something that would generate an index that by default goes to the public API with a header box that says

You are viewing the public API documentation, if you are working on this project you may want the
developer docs.

Where "developer docs" links to an alternate index.html compiled with --no-defaults --passes "collapse-docs" --passes "unindent-comments", and a similar header linking back to the public API.

Something simple and discoverable like cargo doc --include-dev-docs or something. You could probably do this without modifying too much by just outputting the docs in a doc/dev before the private type stripping pass and then again after the pass.

LinearZoetrope commented Sep 20, 2017

I feel like it would be nice to optionally have cargo doc generate both developer and public documentation. Something that would generate an index that by default goes to the public API with a header box that says

You are viewing the public API documentation, if you are working on this project you may want the
developer docs.

Where "developer docs" links to an alternate index.html compiled with --no-defaults --passes "collapse-docs" --passes "unindent-comments", and a similar header linking back to the public API.

Something simple and discoverable like cargo doc --include-dev-docs or something. You could probably do this without modifying too much by just outputting the docs in a doc/dev before the private type stripping pass and then again after the pass.

@steveklabnik

This comment has been minimized.

Show comment
Hide comment
@steveklabnik

steveklabnik Sep 20, 2017

Member

A small note here, we plan on deprecating the --no-defaults --passes "collapse-docs" --passes "unindent-comments" shenanigans and introducing a more straightforward flag to generate private docs into Rustdoc.

Member

steveklabnik commented Sep 20, 2017

A small note here, we plan on deprecating the --no-defaults --passes "collapse-docs" --passes "unindent-comments" shenanigans and introducing a more straightforward flag to generate private docs into Rustdoc.

@hobofan

This comment has been minimized.

Show comment
Hide comment
@hobofan

hobofan Jan 17, 2018

For anyone stumbling upon this, rust-lang/rust#44138 has implemented the --document-private-items flag, which does the same as --no-defaults --passes "collapse-docs" --passes "unindent-comments".

cargo rustdoc -- --document-private-items

hobofan commented Jan 17, 2018

For anyone stumbling upon this, rust-lang/rust#44138 has implemented the --document-private-items flag, which does the same as --no-defaults --passes "collapse-docs" --passes "unindent-comments".

cargo rustdoc -- --document-private-items
@glandium

This comment has been minimized.

Show comment
Hide comment
@glandium

glandium Mar 20, 2018

While cargo rustdoc -- --document-private-items is nice, it also doesn't work with virtual manifests (Cargo.toml with only a workspace defined), so a cargo doc option would be even nicer.

glandium commented Mar 20, 2018

While cargo rustdoc -- --document-private-items is nice, it also doesn't work with virtual manifests (Cargo.toml with only a workspace defined), so a cargo doc option would be even nicer.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment