Mobile Docs

Warning

This repo is deprecated. Check the code repos for associated docs.

This repository is used to build the documentation site for AeroGear Mobile Services. To view the documentation please visit docs.aerogear.org.

Our goal is to help users of AeroGear projects "understand things well and not feel like they’re dealing with a capricious minor god instead of a product." ^[1]

This readme introduces the standards for AeroGear docs.

Prerequisites

To work with mobile-docs you must have the latest antora version installed on your local machine.

• link:https://docs.antora.org/

Getting Started

If you just want to edit or verify technical content, you can edit the file and jump to:

• Using Antora to convert asciidoc to html

• Using Antora with a live preview

Concepts, Procedures and Reference

Concept

An introduction to a new term, process, module or component. For example, "Mobile Service" : what is it? why do I care? and how does it fit into my development environment?

• Name file by slugifying title

• Prefix filenames with con_

Procedure

The important information that gets me using AeroGear software, for example, write your procedure by answering the following questions:

• Who should perform this procedure?

• Why am I performing this procedure? benefits or context in a higher level user story

• What is the object of the task? eg adding a dashboard.. to what?

• What do I need to know and/or do before installing or provisioning the software?

• What do I need to do to provision the software?

• What are the minimum configuration tasks that I need to do to get value from the software?

• What additional information would be useful after completing procedure (eg, next steps)

• Name file by slugifying title

• no prefix on filenames

See Creating Procedures

Reference

Information I might need to debug or extend the normal usage of AeroGear software. For example:

• API syntax and definitions

• Configuration optionss

• Name file by slugifying title

• Prefix filenames with ref_

Writing AeroGear Documentation

1. If you make a filename change (eg adding or renaming a file), you must update the appropriate modules/ROOT/nav.adoc file.

2. Test your changes using Antora

3. Determine which functionality is this documentation related to?

   • Push

   • Metrics

   • Common to all mobile services

   • Common to all services or SDKs but with some information that is specific to each.

     With this information, you should be able to determine where the file should be located in the repo, eg modules/ROOT/push

     If you intend to reuse a part of a file, create a partial in modules/ROOT/_partials and refer to it using an include.

     Only create links to the files in the pages directory. Links to files under _partials will not resolve.

4. Stick to present tense, eg `When you add the dashboard, it appears on `, not `When you add the dashboard, it will appear on `

AsciiDoc

For a ful list of asciidoc syntax, see the quick reference, note the following syntax to avoid:

• Headings using --, ~~, ^^, ++ syntax

• Markdown

• Source block without syntax. Try to use syntax highlighting where possible, for example [source, bash]

Using Antora to convert asciidoc to html

Note	When you create a PR, an Antora preview is automatically generated. and is linked to the PR. If you are making a small change, this may be sufficient.

After modifying documentation, you can validate your changes and preview the results by:

1. Install Antora v2 globally as described in their install guide.

2. Fork this repo and set up origin and upstream remotes.

3. Change to the mobile-docs directory.

4. Run antora:

   ./bin/quick-build.sh local-site.yml

   Note: <site-file> refers to either:

   • local-site - your current directory

   • site.yml - the master branch of the github repo

     When building for publication use:

     ./bin/build.sh

Note	After changes to antora-ui, you might need to run 'antora --pull --clean <site-file>' to pick up those changes.

The site.yml currently creates HTML for:

• master branch of this repo

• v1.0 branch of this repo

• master branch of the https://github.com/aerogear/mobile-security repo

Using Antora with a live preview

Prerequisites

• Node.js

To create a live preview that picks up changes while working on the docs:

1. Install the dependencies specified in package.json.

   npm install

2. Run the following command to watch for changes in the modules folder and automatically rebuild the site.

   npm run watch

   You should see new output in the terminal window when changes are made. This indicates the site is being rebuilt automatically.

3. In a separate terminal, run the following command to serve the website.

   npm run serve

   This starts a static server that serves the built website. It will automatically open your browser and the current page will reload any time the site is rebuilt.

Note	It usually takes 3-5 seconds to see the changes automatically reflected in your browser.

Editing

After reviewing a html file, you might identify a change. When editing a file, you might find that the content is not in the associated adoc file, because it’s rendered by using the asciidoc include command. You can edit the included file, but note that editing the source file can have unintended effect. For example, when editing the registering-an-app.adoc, avoid problems by:

1. Regex search for include.*registering-an-app across the whole repo.

2. Review the list of files from this search to understand of the context of the content.

3. Use your judgement when editing the file to make sure the content is appropriate for each rendering of that content.

Publishing

Currently, the publishing process is manual:

1. Run antora using following command:

   ./bin/build.sh

2. Review the output (build\site\index.html) for errors. Correct if required.

   Note	Check for correct styling changes too.

3. Make a PR against https://github.com/aerogear/docs.aerogear.org

Note	This repo contains more than just the output of mobile-docs repo. See https://github.com/aerogear/docs.aerogear.org/blob/master/README.adoc for more details.

Remote Repos

No remote repos were harmed in the production of this documentation ;)

However, references to code maybe be included as follows:

1. Decide on a name for the snippet, eg push-ios-register

2. Create a partial in mobile-docs, eg https://github.com/aerogear/mobile-docs/blob/master/modules/ROOT/pages/_partials/push-ios-register.inc

3. Reference the code file you want to use (with a tags filter):

    // include::https://raw.githubusercontent.com/aerogear/ios-showcase-template/push-push/ios-showcase-template/push/PushHelper.swift[tags=push-ios-register]

4. Add tags to the code repo, eg

   // tag::push-ios-register[]
       public func registerUPS(_ deviceToken: Data) {
           AgsCore.logger.info("Registered for notifications with token")
   
           var config = UnifiedPushConfig()
           config.alias = "Example App"
           config.categories = ["iOS", "Example"]
   
           AgsPush.instance.register(
               deviceToken,
               config,
               success: {
                   AgsCore.logger.info("Successfully registered to Unified Push Server")
               },
               failure: { (error: Error!) in
                   AgsCore.logger.error("Failure to register for on Unified Push Server: \(error)")
               }
           )
       }
   // end::push-ios-register[]

5. Edit adoc file with the following to display the content:

    include::{partialsdir}/push-ios-register.inc-rantora.adoc[]

   Note	You need to run mobile-docs:/bin/build.sh <site>.yml to make sure the temp files are in place when building site

Writing tools

You can lint the English prose you’ve written using the following command:

$ ./node_modules/write-good/bin/write-good.js <path-to-adoc>

The output gives you suggestions as to how to improve the text, but many suggestions can be ignored.

Troubleshooting

If you encounter problems creating a preview:

1. Delete the build and .cache directories.

2. Uninstall antora:

   npm uninstall -g @antora/cli
   npm uninstall -g @antora/site-generator-default

3. Reinstall antora v2:

   npm i -g @antora/[email protected] @antora/[email protected]

4. Run

   /bin/quick-build.sh local-site.yml

If there is still an issue, contact aerogear at googlegroups.com.

---

1. Laura Bailey