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

Overhaul Style Guide #2838

Merged
merged 39 commits into from
Dec 8, 2016
Merged

Overhaul Style Guide #2838

merged 39 commits into from
Dec 8, 2016

Conversation

stevepiercy
Copy link
Member

This PR addresses issue #2633, and expands the Style Guide as an easy reference for documentation authors.

Request review and feedback.

@stevepiercy
Rename Typographical Conventions to Style Guide
fb88f05
@stevepiercy
Add Introduction
8cc4f78 
- add how to update and contribute
- add file conventions
- add line conventions
@stevepiercy
Merge pull request #2824 from stevepiercy/style-guide
d204595 
Rename Typographical Conventions to Style Guide
@stevepiercy
Add moar sections
18a6375 
- trailing white space
- indentation
- split line lengths and paragraphs
@stevepiercy
Merge pull request #2825 from stevepiercy/style-guide
d236a70 
Add Introduction and other sections
@stevepiercy
Add Page structure section
f69e903 
- add description
- add introduction
- add headings
- add grammar, spelling, capitalization preferences
@stevepiercy
Merge pull request #2826 from stevepiercy/style-guide
8abaf3c 
Add Page structure section
@stevepiercy
Add section structure
7285651
@stevepiercy
update headings
2954362
@stevepiercy
add links
c13e6cc
@stevepiercy
add topic
e33b2ce
@stevepiercy
add syntax highlighting
ff8acd6
@stevepiercy
add code block options
90db2bc 
- add literal includes
- add displaying long commands
- add sphinx to intersphinx
- garden
@stevepiercy
Merge pull request #2828 from stevepiercy/style-guide
afce288 
More style guide updates
@stevepiercy
add literalinclude options
60ff6ab
@stevepiercy
Merge pull request #2829 from stevepiercy/style-guide
2e62254 
add literalinclude options
@stevepiercy
improve include section
cdee90a 
- start work on inline and block reST sections
@stevepiercy
improve links section
a7f3065 
- add rendering of headings for testing
- add topic directive
- dedent displaying code
- add italics, strong
- add Pytyon modules, classes, methods, functions
- add tables heading (WIP)
- add API documenation (WIP)
@stevepiercy
comment out autodoc of TranslationString to get docs to build on Trav…
88dd1fc 
…is-CI

https://travis-ci.org/Pylons/pyramid/jobs/178536008#L406
@stevepiercy
Merge pull request #2833 from stevepiercy/style-guide
faf4ab2 
more style guide updates
@stevepiercy
add todo Sphinx extension for todo blocks
bf5c9ea 
- add lists, tables, danger, todo, comments
@stevepiercy
Merge pull request #2836 from stevepiercy/style-guide
478b439 
add todo Sphinx extension for todo blocks
@stevepiercy
replace description with meta
f4518e7 
- add parsed-literals
@stevepiercy
add feature versioning, seealso
78254d4
@stevepiercy
add glossary
d586ff5
@stevepiercy
add toctree
d1d6a7d
@stevepiercy
add cross-referencing
d7a6a90
@stevepiercy
add sphinx extensions
d7150db
@stevepiercy
Merge pull request #2837 from stevepiercy/style-guide
c6b5b95 
Add more sections to the Style Guide
@stevepiercy
fix warning about duplicate name
fa84255
@stevepiercy
Merge pull request #2843 from stevepiercy/style-guide
351a741 
restore Typographical Conventions, an edited and condensed version of…
@stevepiercy
Copy link
Member Author

@bertjwregeer Typo Conv is back and better than ever.

One day, when we have a useful pylonsproject.org, I'll move the Style Guide over there to share across all Pylons Project projects.

@stevepiercy
Copy link
Member Author

We're close to releasing the new pylonsproject.org. However, I want to use Sphinx to render style-guide.rst because it is for docs and uses Sphinx markup, so it makes sense to have it here and rendered.

If there are no further suggestions or objections, then I'll merge this PR this evening.

@digitalresistor
Copy link
Member

There are things in the Typographical Conventions that don't belong there.

Such as what a bulleted list is, or headings. It needs to contain a little information for users to know "Ah, that means it's code" or "that is a command I run" or "this is a warning".

Here's some typographical conventions from three random books I pulled down off my bookshelf:

For Dummies:
fullsizerender 3

Cisco Press:
fullsizerender 2

O'Reilly:
fullsizerender 4

@stevepiercy
Copy link
Member Author

@bertjwregeer Updated. I'll merge this evening if there are no further suggestions.

@digitalresistor
Copy link
Member

👍 much better. Thanks!

@stevepiercy
Copy link
Member Author

Thanks for the feedback!

@stevepiercy stevepiercy merged commit 05467bd into master Dec 8, 2016
@stevepiercy stevepiercy deleted the style-guide branch December 8, 2016 23:35
@stevepiercy stevepiercy mentioned this pull request Dec 11, 2016
Closed
19 tasks
This was referenced Jan 22, 2017
Closed
Closed
Closed
@pyup-bot pyup-bot mentioned this pull request Feb 26, 2017
Merged
@pyup-bot pyup-bot mentioned this pull request Apr 30, 2017
Merged
This was referenced Jun 26, 2017
Closed
Merged
@pyup-bot pyup-bot mentioned this pull request Jul 3, 2017
Closed
This was referenced Jul 10, 2017
Closed
Closed
@pyup-bot pyup-bot mentioned this pull request Jul 24, 2017
Closed
This was referenced Sep 29, 2017
Merged
Closed
Merged
@pyup-bot pyup-bot mentioned this pull request Dec 12, 2017
Merged
@pyup-bot pyup-bot mentioned this pull request Jun 30, 2020
Closed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers
No reviews
Assignees

@stevepiercy stevepiercy

Labels
docs
Projects
None yet
Milestone
1.8
Development

Successfully merging this pull request may close these issues.
2 participants
@stevepiercy @digitalresistor