Reorganize doc guidelines into multiple pages

The existing doc guidelines page attempts to combine too many different
topics at once and includes information that does not pertain directly
to the documentation. This reorganization is intended to make each type
of information easier to find. For example, some have found it difficult
to find the documentation style guidelines (see, e.g.,
QubesOS/qubes-issues#6701#issuecomment-875875610). This reorganization
allows us to assign more specific titles to each page.

General changes:
- Create new page for contribution instructions
- Create new page for website style guide
- Create new page for continuous integration
- Rename existing "style guide" to "visual style guide" in order to
  avoid ambiguity with new doc and website style guides
- Retain existing page solely for doc style guide
- Update page names and permalinks
- Update existing links
- Update doc index
pull/182/head adw_a540575f
Andrew David Wong 1 year ago
parent d29a2ddfd2
commit a540575f0e
No known key found for this signature in database
GPG Key ID: 8CE137352A019A17
  1. 9
      CONTRIBUTING.md
  2. 15
      README.md
  3. 7
      _data/doc-index.yml
  4. 4
      _data/includes.yml
  5. 0
      _data/visual-style-guide-page.yml
  6. 0
      _data/visual-style-guide.yml
  7. 4
      _includes/doc-content.html
  8. 8
      _includes/variables.html
  9. 24
      _includes/visual-style-guide.html
  10. 4
      _sass/_docs.scss

@ -3,7 +3,10 @@ Contributing to `qubesos.github.io`
Thank you for your interest in contributing to `qubesos.github.io`, the Qubes OS
Project's official website repository! Please take a moment to read our
[Documentation Guidelines](https://www.qubes-os.org/doc/doc-guidelines/) before contributing. These guidelines are
important to maintaining high standards of quality, and following them will
increase the likelihood that your contribution will be accepted.
[website style guide](https://www.qubes-os.org/doc/website-style-guide/) before
contributing. These guidelines are important to maintaining high standards of
quality, and following them will increase the likelihood that your contribution
will be accepted.
To contribute to the documentation, please see [how to edit the
documentation](https://www.qubes-os.org/doc/how-to-edit-the-documentation).

@ -105,18 +105,11 @@ Instructions
exit
Documentation Guidelines
------------------------
Our [Documentation Guidelines](https://www.qubes-os.org/doc/doc-guidelines/) include:
- How to Report Issues
- How to Contribute
- Contribution Suggestions
- Style Guidelines
- Markdown Conventions
- Git Conventions
Documentation
-------------
Please carefully read these guidelines before submitting a pull request.
To contribute to the documentation, please see [how to edit the
documentation](https://www.qubes-os.org/doc/how-to-edit-the-documentation).
### Dependencies & Third Party Docs ###

@ -141,11 +141,14 @@
sub-pages:
- url: /faq/
- url: /doc/package-contributions/
- url: /doc/doc-guidelines/
- url: /gsoc/
- url: /gsod/
- url: /doc/how-to-edit-the-documentation/
- url: /doc/documentation-style-guide/
- url: /doc/website-style-guide/
- url: /doc/continuous-integration/
- url: /doc/usability-ux/
- url: /doc/style-guide/
- url: /doc/visual-style-guide/
- url: /research/
- url: /doc/devel-books/

@ -12,8 +12,8 @@
icon: fa-question-circle
- text: Page Source on GitHub
icon: fa-github
- url: /doc/doc-guidelines/
text: Doc Guidelines
- url: /doc/how-to-edit-the-documentation/
text: How to Edit the Docs
icon: fa-file-signature
- url: /doc/issue-tracking/
text: Report Bug

@ -23,8 +23,8 @@
{% if perm_last_part == "xsa" %}
{% include sec-xsa.html %}
{% endif %}
{% if perm_last_part == "style-guide" %}
{% include style-guide.html %}
{% if perm_last_part == "visual-style-guide" %}
{% include visual-style-guide.html %}
{% endif %}
<!-- END CONTENT -->
<!-- Closing HTML for doc content -->

@ -21,7 +21,7 @@
<!-- Team page -->
{% assign team-page = site.data.team-page %}
<!-- Style guide page -->
{% assign style-guide-page = site.data.style-guide-page %}
{% assign visual-style-guide-page = site.data.visual-style-guide-page %}
{% else %}
<!-- Page language -->
{% assign lang = "/" | append: page.lang %}
@ -63,9 +63,9 @@
{% assign team-page = site.data.team-page %}
{% endif %}
<!-- Style guide page -->
{% assign style-guide-page = site.data.translation[page.lang].style-guide-page %}
{% if style-guide-page == nil or style-guide-page.size == 0 %}
{% assign style-guide-page = site.data.hcl %}
{% assign visual-style-guide-page = site.data.translation[page.lang].visual-style-guide-page %}
{% if visual-style-guide-page == nil or visual-style-guide-page.size == 0 %}
{% assign visual-style-guide-page = site.data.hcl %}
{% endif %}
{% endif %}
<!-- Doc link -->

@ -1,14 +1,14 @@
<!-- Variables -->
{% include variables.html %}
{% assign fonts = style-guide-page | where_exp: "item", "item.htmlsection == 'fonts'" | first %}
{% assign colors = style-guide-page | where_exp: "item", "item.htmlsection == 'colors'" | first %}
{% assign icons = style-guide-page | where_exp: "item", "item.htmlsection == 'icons'" | first %}
{% assign logos = style-guide-page | where_exp: "item", "item.htmlsection == 'logos'" | first %}
{% assign fonts = visual-style-guide-page | where_exp: "item", "item.htmlsection == 'fonts'" | first %}
{% assign colors = visual-style-guide-page | where_exp: "item", "item.htmlsection == 'colors'" | first %}
{% assign icons = visual-style-guide-page | where_exp: "item", "item.htmlsection == 'icons'" | first %}
{% assign logos = visual-style-guide-page | where_exp: "item", "item.htmlsection == 'logos'" | first %}
<!-- Style guide -->
<h2 id="fonts"> {{ fonts.title }}</h2>
<p>{{ fonts.paragraph }}</p>
<div class="style-guide">
{% for font in site.data.style-guide.fonts %}
<div class="visual-style-guide">
{% for font in site.data.visual-style-guide.fonts %}
<div class="row">
<div class="col-lg-6 col-md-6 focus">
<div class="font {{font.class}}"> {{ fonts.snippets[0].snippet }}</div>
@ -23,8 +23,8 @@
<h2 id="colors">{{ colors.title }}</h2>
{% assign snippet = colors.paragraph[0].snippets %}
<p>{{ snippet[0].snippet }} <strong>{{ snippet[1].snippet }}</strong> {{ snippet[2].snippet }}</p>
<div class="style-guide">
{% for color in site.data.style-guide.colors %}
<div class="visual-style-guide">
{% for color in site.data.visual-style-guide.colors %}
{% if color.type == "grayscale" %}
<div class="swatch more-bottom more-right">
<div class="color add-bottom bg-{{color.class}}"></div>
@ -36,8 +36,8 @@
</div>
{% assign snippet = colors.paragraph[1].snippets %}
<p>{{ snippet[0].snippet }} <strong>{{ snippet[1].snippet }}</strong> {{ snippet[2].snippet }}</p>
<div class="style-guide">
{% for color in site.data.style-guide.colors %}
<div class="visual-style-guide">
{% for color in site.data.visual-style-guide.colors %}
{% if color.type == "colors" %}
<div class="swatch more-bottom more-right">
<div class="color add-bottom bg-{{color.class}}"></div>
@ -72,8 +72,8 @@
{% endif %}
{% endfor %}
</p>
<div class="style-guide">
{% for logo in site.data.style-guide.logos %}
<div class="visual-style-guide">
{% for logo in site.data.visual-style-guide.logos %}
{% for version in logo.versions %}
<div class="row more-bottom">
<div class="col-lg-4 col-md-4">

@ -17,13 +17,13 @@
/* Style Guide */
@mixin style-guide-focus() {
@mixin visual-style-guide-focus() {
background-color: $gray-lighter;
border-radius: $border-radius-base;
padding: $spacing-unit;
}
.style-guide {
.visual-style-guide {
.swatch {
display: inline-block;

Loading…
Cancel
Save