Markdown primer

Adjust's SDK documentation is written using Sphinx and a superset of Markdown called MyST. MyST grants the writer access to some additional features found in reStructuredText, but with a familiar Commonmark-like syntax.

This primer demonstrates the use of some of the custom features used in the Adjust SDK documentation.

Basic convention notes

Use the following conventions when contributing to the SDK documentation:

• Use asterisks (*) instead of hyphens (-) for unordered lists.
• Use asterisks (*) instead of underscores (_) to format italicized and bold text.
• Use inline formatting for links ([link-text](link-destination)) rather than reference links.

Comments

You can use the a percent symbol (% ) to write comments into Markdown files. These comments aren't rendered when the Sphinx site is generated, but can be useful for fencing off reusable content or to add context for writers.

Code fences

MyST enables the use of 2 different syntaxes for code fences:

• Backtick fences
• Colon fences

Note: For consistency, always use backtick code fences for code examples and colon code fences for markup.

```java
Adjust.setOfflineMode(true)
```

:::{note}
This is a note
:::

Fence depth

If you are nesting fenced elements, the parent element must contain one more fence marker than its direct child. For example, if you want to nest 3 items enclosed in colon fences, the top level must have 5 colons, the next level 4, and the deepest level 3.

:::::{top-level}

This is the top level. It has a child.

::::{sub-level 1}

This is the second level. It's the child of the topLevel and has its own child.

:::{sub-level 2}

This is the final child element.

:::
::::
:::::

Syntax highlighting

Sphinx uses a syntax highlighting library called Pygments to highlight source code in code fences. A full list of supported lexers is available here. To highlight code blocks, add the lexer name immediately after the opening code fence.

Note: Use the full name of the language for source highlighting (for example: objective-c rather than objc). This makes the source Markdown more readable and assigns readable names to code tabs.

```objective-c
[Adjust setEnabled:YES];
```

Admonitions

Use admonitions to highlight different types of information. Admonitions can contain markdown syntax, images, and any other content you wish to include. If you want to add content in code fences, make sure child elements are nested.

Note: For consistency, use colon code fences for admonitions.

:::{note}
This is a  **note**.
:::

:::{important}
This is an important piece of information
:::

You can find a full list of supported admonitions here.

By default, admonitions are given a title that matches their type. For example: Tip, Warning, Important. You can assign a custom title by passing it to a generic admonition block, then assign a class to style the block.

:::{admonition} Special install instructions
:class: important

You need to read this information *before* you install the SDK.
:::

See the MyST documentation for more information.

Dropdowns

The Sphinx Design library provides the ability to hide additional information in dropdowns. You can use a similar syntax to that used in admonitions to hide additional information in collapsible blocks.

Note: Only additional information – such as examples – should be placed in dropdowns. Any required information must not be hidden.

:::{dropdown} Additional information
This information is nice to know, but not essential.
:::

See the Sphinx design documentation.

Reusing content

If you need to reuse content from another page, you can do this by using an include directive. This is useful if you want to import code snippets, parameter tables, or other content which may change between updates to ensure they remain up-to-date across the documentation.

The include directive imports an entire file's content by default. There are two ways to import a selection of content from a file:

1. Specify a start-line and end-line.
2. Specify what content to start-after and end-before. These are exact strings that form the bookends of content you want to import, such as two headers that start and end a block of text.

The second method is preferred for importing prosaic content as it's less prone to breakage. To make it easier to fence off content for importing, you can use comments to specify where the content begins and ends.

Below is some content I'd like to reuse.

% content start

This content is **reusable**.

% content end

I'm going to reuse my content here.

:::{include} /path/to/file.md
:start-after: content start
:end-before: content end
:::

Function documentation

When writing function documentation you should use the conventions of Sphinx autodoc domains. Sphinx doesn't support domains for all languages used across Adjust's SDKs, so for the sake of consistency all function documentation should be written using the default domain.

A typical function invocation looks like this:

% Class method configWithAppToken [1]

::::{function} configWithAppToken(appToken, environment,allowSuppressLogLevel) [2]
:noindex: [3]

Initialize the configuration object with your Adjust app token. [4]

{#ios-configwithapptoken-invocation} [5]
```objective-c
+ (nullable ADJConfig *)configWithAppToken:(nonnull NSString *)appToken
                               environment:(nonnull NSString *)environment
                     allowSuppressLogLevel:(BOOL)allowSuppressLogLevel;
```

[6]
:param appToken: Your Adjust app token
:type appToken: NSString
:param environment: The environment your app is running in
:type environment: NSString
:param allowSuppressLogLevel: Whether to allow all logging to be suppressed
:type allowSuppressLogLevel: BOOL

[7]
:returns: A config object initialized with the provided params
:rtype: ADJConfig

% configWithAppToken snippet [8]

{tab-set-code} [9]

```swift
let yourAppToken = "{YourAppToken}"
let environment = ADJEnvironmentSandbox as? String
let adjustConfig = ADJConfig(
   appToken: yourAppToken,
   environment: environment)
```

```objective-c
NSString *yourAppToken = @"{YourAppToken}";
NSString *environment = ADJEnvironmentSandbox;
*adjustConfig = [ADJConfig configWithAppToken:yourAppToken
                                  environment:environment];
```

```javascript
setupWebViewJavascriptBridge(function(bridge) {
   var yourAppToken = yourAppToken;
   var environment = AdjustConfig.EnvironmentSandbox;
   var adjustConfig = new AdjustConfig(yourAppToken, environment);
});
```

:::

% endSnippet [8]

::::

% Class method end [1]

This example includes the following:

1. Comments (%) denoting the beginning and ending of the class method.
2. A function directive containing the function name and a list of parameters.
3. A :noindex: parameter to prevent Sphinx trying to index duplicate function names.
4. A description of what the function does.
5. A named code block containing the public function from the source code. This name is used to generate a tooltip so that users can hover over the method name in documentation to see the code invocation.
6. A list of parameters and data types formatted as a field list.
7. A list of return values (if applicable) formatted as a field list.
8. Comments (%) denoting the beginning and ending of the reusable code snippet.
9. A tab set containing the code snippets.

In your documentation file, you might include some of this class information as follows:

To initialize the Adjust SDK, you need to create a config object. To do this, call the [`configWithAppToken` method](#ios-configwithapptoken-invocation) with your app token and operating environment.

:::{include} /ios/reference/AdjustConfig/index.md
:start-after: configWithAppToken snippet
:end-before: Snippet end
:::