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

Docs: Use :silent on import statements #2337

Merged
merged 2 commits into from Jan 7, 2019

Conversation

Projects
None yet
3 participants
@zakpatterson
Copy link
Contributor

zakpatterson commented Jan 2, 2019

Note: I just applied this change to a single file. Feel free to close this if it's not desired, or let me know if this seems better and I'll happily apply the same change to all the docs.

:silent is desirable to avoid showing the user repl responses
about each individual import. Usually we want to show the
user the types inferred from repl lines, but for import
statements there's no value. The proof the import was
found is in the docs compiling at all.

The tradeoff here is that when the markdown is rendered, there will be a break between blocks that otherwise would be in the same file

Use :silent on import statements
:silent is desirable to avoid showing the user repl responses
about each individual import. Usually we want to show the
user the types inferred from repl lines, but for import
statements there's no value. The proof the import was
found is in the docs compiling at all.

@zakpatterson zakpatterson changed the title Use :silent on import statements [WIP] Use :silent on import statements Jan 2, 2019

@zakpatterson zakpatterson changed the title [WIP] Use :silent on import statements [WIP] Docs: Use :silent on import statements Jan 2, 2019

@rossabaker
Copy link
Member

rossabaker left a comment

I think this is a good trade. I've adopted this technique using remark.js+tut for presentations, and I see no reason it wouldn't also be a win here.

@zakpatterson

This comment has been minimized.

Copy link
Contributor Author

zakpatterson commented Jan 4, 2019

Great I'll proceed and apply this to the other files soon.

Use tut:silent for input statements
Also remove all instances of tut📖silent. :book only
affects the output, so there's no reason to use it with :silent.

@zakpatterson zakpatterson changed the title [WIP] Docs: Use :silent on import statements Docs: Use :silent on import statements Jan 4, 2019

@zakpatterson

This comment has been minimized.

Copy link
Contributor Author

zakpatterson commented Jan 4, 2019

Ok, I fixed up all the import blocks, using tut:silent instead of tut:book. For consistency, I also removed all instances of tut:book:silent in favor of tut:silent, because without output, :book does nothing.

@rossabaker
Copy link
Member

rossabaker left a comment

👍 Thanks!

@ChristopherDavenport ChristopherDavenport merged commit c0bc9c8 into http4s:master Jan 7, 2019

1 check passed

continuous-integration/travis-ci/pr The Travis CI build passed
Details

@zakpatterson zakpatterson deleted the zakpatterson:docs-refactor-imports branch Jan 8, 2019

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