#18 New module: AsciiDoc for Fedora Documentation Writers (part of #8)
Merged 3 years ago by zoglesby. Opened 3 years ago by jflory7.

file modified
+2 -1
@@ -3,7 +3,7 @@ 

  name: fedora-docs

  

  # Title will be visible on the page.

- title: Fedora Docs

+ title: Fedora Docs Team

  

  # If you don't plan to have multiple versions of the docs (for example, to document multiple versions of some software), you can ignore this field. Otherwise, change "master" to a specific version.

  version: master
@@ -15,3 +15,4 @@ 

  nav:

  - modules/ROOT/nav.adoc

  - modules/contributing/nav.adoc

+ - modules/asciidoc-fedora/nav.adoc

@@ -0,0 +1,3 @@ 

+ * xref:index.adoc[AsciiDoc for Fedora]

+ ** xref:markup.adoc[Markup]

+ ** xref:reusable-attributes.adoc[Reusable attributes]

@@ -0,0 +1,7 @@ 

+ = AsciiDoc for Fedora Documentation Writers

+ 

+ This documentation section provides advice, tips, and resources for the Fedora Community writing AsciiDoc for Fedora documentation.

+ The purpose of this section is not to duplicate what already exists, but to point you the right way.

+ The idea is for you to spend less time remembering AsciiDoc or Antora nitpicks, and more time writing good docs!

+ 

+ _Use the navigation bar in the side to navigate this section._

@@ -0,0 +1,85 @@ 

+ = AsciiDoc markup

+ Fedora Documentation Team <docs@lists.fedoraproject.org>

+ v0.0.1, 2020-08-26

+ :toc:

+ 

+ This page shares general information about writing in AsciiDoc as well as Fedora/Antora-specific syntax that comes up often in Fedora Documentation.

+ 

+ 

+ [[basics]]

+ == AsciiDoc basics

+ 

+ [quote,asciidoctor.org]

+ ____

+ AsciiDoc is a lightweight markup language for authoring notes, articles, documentation, books, web pages, slide decks and man pages in plain text.

+ ____

+ 

+ https://asciidoctor.org/docs/asciidoc-syntax-quick-reference/[*AsciiDoc Syntax Quick Reference*]::

+ Handy cheat sheet of what the AsciiDoc markup looks like.

+ Use this for quick references and checking up on how to formatting, lists, media content (images and video), table of contents, and more.

+ 

+ https://asciidoctor.org/docs/asciidoc-recommended-practices/[*AsciiDoc Recommended Practices*]::

+ Best practices about writing in AsciiDoc.

+ Most importantly, note that https://asciidoctor.org/docs/asciidoc-recommended-practices/#one-sentence-per-line[every sentence should be on its own line].

+ 

+ 

+ [[snippets]]

+ == Fedora Documentation snippets

+ 

+ When you write Fedora Documentation, some things come up frequently.

+ They may not be documented in general AsciiDoc documentation, like on `asciidoctor.org`.

+ This section contains handy references for Fedora Documentation writers to copy and paste in their own AsciiDoc documents.

+ 

+ [[internal-link]]

+ === Link to a page in the same repository

+ 

+ Use the local path from the directory root to the AsciiDoc file name.

+ 

+ .Example 1

+ [source,adoc]

+ ----

+ xref:page-name.adoc

+ ----

+ 

+ .Example 2

+ [source,adoc]

+ ----

+ xref:packaging/policy/rules.adoc

+ ----

+ 

+ [[module-link]]

+ === Link to a page in the same repository, but different module

+ 

+ Like an internal link, but use a colon (`:`) to separate the module name.

+ If you are not sure if you need this, you likely don't!

+ Multiple modules bundled in the same repository is not currently a common scenario in Fedora Documentation.

+ 

+ .Example 1

+ [source,adoc]

+ ----

+ xref:module::page-name.adoc

+ ----

+ 

+ .Example 2

+ [source,adoc]

+ ----

+ xref:council:policy/guiding-policy.adoc

+ ----

+ 

+ [[external-antora-link]]

+ === Link to a page in a different Fedora Documentation repository

+ 

+ Link to another Fedora Documentation page that exists in another repository.

+ Note that you *must* use the `name` field specified in the `antora.yml` file in the other repository or it will not work.

+ 

+ .Example 1

+ [source,adoc]

+ ----

+ xref:name:module:page-name.adoc

+ ----

+ 

+ .Example 2

+ [source,adoc]

+ ----

+ xref:council::code-of-conduct.adoc

+ ----

@@ -0,0 +1,88 @@ 

+ = Reusable attributes

+ Fedora Documentation Team <docs@lists.fedoraproject.org>

+ v0.0.1, 2020-08-26

+ :toc:

+ 

+ This page explains how to use reusable metadata, or attributes, across multiple AsciiDoc documents in Fedora Documentation.

+ 

+ 

+ [[why]]

+ == Why reusable attributes?

+ 

+ Sometimes you may want to use the same data across many AsciiDoc documents.

+ Some examples are below:

+ 

+ * Version releases (e.g. Fedora `N`)

+ * URL prefixes or suffixes (e.g. `https://pagure.io/fesco/issue/`)

+ * Dates and time (e.g. current year, like `2020`)

+ 

+ For these and more use cases, *attributes* allow you to define some metadata in a single place, and reuse it in multiple places.

+ 

+ 

+ == Overview

+ 

+ There are two requirements for your Fedora Documentation project to use attributes.

+ 

+ . Import attributes in your AsciiDoc file

+ . Create an attributes file

+ 

+ 

+ [[attributes-file]]

+ == Create attributes file

+ 

+ First, initialize an attributes file for a specific module, as shown below:

+ 

+ [source,sh]

+ ----

+ .

+ └── ROOT

+     ├── nav.adoc

+     └── pages

+         ├── index.adoc

+         └── _partials

+             └── attributes.adoc

+ ----

+ 

+ This is an example `attributes.adoc` from the xref:diversity-inclusion::index.adoc[Fedora Diversity & Inclusion Team]:

+ 

+ [source,adoc]

+ ----

+ :COMMBLOG: https://communityblog.fedoraproject.org

+ :FISCALYEAR: FY20

+ :FWIKI: https://fedoraproject.org/wiki

+ :YEAR: 2020

+ :MAILINGLIST: https://lists.fedoraproject.org/archives/list/diversity@lists.fedoraproject.org/

+ :MAJOROSVER: 32

+ ----

+ 

+ 

+ [[import]]

+ == Import attributes

+ 

+ Next, import the attributes file into your AsciiDoc document.

+ Placing this macro on the top line will do the rest:

+ 

+ [source,adoc]

+ ----

+ \include::{partialsdir}/attributes.adoc[]

+ ----

+ 

+ 

+ [[use-attributes]]

+ == Use attributes in documentation

+ 

+ After creating an attributes file *AND* import attributes, reference the attributes in AsciiDoc documents with the following syntax:

+ 

+ [source,adoc]

+ ----

+ {ATTRIBUTE}

+ ----

+ 

+ See this example from the Fedora Diversity & Inclusion Team:

+ 

+ [source,adoc]

+ ----

+ *Full consensus* is required to approve new processes, make changes to

+ existing team policies, and tickets requiring

+ https://budget.fedoraproject.org/budget/{FISCALYEAR}/d-i.html[D&I budget].

+ ----

@@ -5,7 +5,6 @@ 

  *** xref:contributing-to-existing-docs.adoc[Contributing to Existing Documentation]

  *** xref:adding-new-docs.adoc[Adding New Documentation to the Site]

  *** xref:local-preview.adoc[Building a Local Preview]

- //** xref:markup.adoc[ASCIIDoc Markup]

  *** xref:git.adoc[Git for docs writers]

  //** xref:working-with-translations.adoc[Working with Translations]

  ** For designers:

This is a first attempt at giving Fedora Documentation Writers a one-
stop location to get started writing AsciiDoc. Instead of trying to
rewrite existing documentation about AsciiDoc, I linked out to helpful
resources maintained by the asciidoctor.org upstream.

However, this commit does write new documentation about handy snippets
to reuse in a Fedora-specific context. I also wrote a short guide on how
to use reusable attributes, since I realize this is something I have
done in many repositories I set up but never documented.

Part of #8 to improve the new contributor experience to Fedora
Documentation with AsciiDoc and Antora.

Screenshot of index page for AsciiDoc for Fedora Documentation Writers module

rebased onto 68b368d

3 years ago

Metadata Update from @jflory7:
- Pull-request tagged with: type - new docs
- Request assigned

3 years ago

This looks great to me. @pbokoc, any concerns?

rebased onto af0119d

3 years ago

Rebased on latest master to fix the merge conflict from #19.

I mentioned this PR several times during the D&I Team Docs Mentoring hour today. It would be really, really, really helpful for me to get this merged!

Pull-Request has been merged by zoglesby

3 years ago

Thanks! I really have not had the time to work on this document since we started reworking it and then I stole @immanetize and got him to come work for me IRL and have driven him hard.

Cool, thank you @zoglesby! :tada: Small world we have here in FOSS. :) Hi @immanetize!