titanium-docs

Website with Guides and API docs for the Titanium SDK (Powered by VuePress).

Getting started

These docs aim to be a hybrid solution of Markdown bases guides and dynamically generated docs for API references using the existing apidoc from Titanium.

Installation

git clone https://github.com/tidev/titanium-docs.git
cd titanium-docs
npm i

Development

VuePress supports a dev mode with hot reloading for a convenient developing experience.

npm run docs:dev

Now start editing the docs and you can immediatly see the results in your browser.

Building the docs

There are currently a few manual steps required to build the docs which we aim to consolidate into a single build step while this project moves foreward.

✅ For convenience the repo currently contains a pre-generate api.json so you can skip this if you just want to play with the new docs.

The following steps assume you have checked out this repo parallel to Titanium so that your folder structure looks like this:

./
├── titanium_mobile/
└── titanium-docs/

Now generate the api.json into the docs/api folder

npm run docs:metadata

Finally, let VuePress build the awesome new docs.

cd ../titanium-docs
npm run docs:build

This will output the statically rendered docs into docs/.vuepress/dist.

Versioning

Run the script with a command line argument of the version you wish to create. e.g.,

npm run docs:version 8.0

This will preserve all documents currently in the docs directory and make them available as documentation for version 8.0.

For more info please refer to the versioning guide.

Migrating docs to VuePress

VuePress renders gorgeously looking documentation directly from markdown files. This means that our currents guides and parts of the api docs have to be migrated to markdown files. Thanks to VuePress they can be enhanced with Vue components to bypass the restriction of markdown in terms of rendering complex HTML structures.

Writing guides in VuePress

Guides reside under docs/guide and a few documents already have been ported as examples. However none of those guides are complete yet.

To add a new guide first create a new markdown file under docs/guide. To add it to the sidebar navigation open docs/.vuepress/config.js and edit the /guide/ section under themeConfig.sidebar. The key you want to add is the name of the new markdown file without the .md extension.

module.exports = {
  themeConfig: {
    sidebar: {
      '/guide/': [
        {
          title: 'Titanium Guides',
          collapsable: false,
          children: [
            '',
            'getting-started',
            'first-app'
            'my-new-guide'
          ]
        }
      ],
     // ...
    }
  }
}

Adding API docs

In theory the api.json contains all required information to automatically generate markdown files. However, some APIs contain very detailed description and various examples which are just better to maintain directly in markdown files here than in their .yaml counterpart in Titanium's apidoc. All other information regarding the API for a type in Titanium is then taken from the api.json. This creates a clear seperation of extensive documentation and simple api reference.

To automatically migrate a type over to these docs you can run the migration script.

node scripts/migrate.js

This will parse docs/api/api.json and generate the missing markdown files.

You may need to adjust the automatically generated content and fix any markdown issues or adjust the front matter section to properly display links throughout the docs.

Apart of the predefined variables from VuePress, API pages support the following additional variables:

Name	Descriptions
metadataKey	Fully qualified type name which is used to find metadata for a type in api.json. The page title will be used if this is not set.

Once you have made sure the automatically generated markdown is correct you can add the new type to the sidebar in docs/.vuepress/config.js under the /api/ key.

Deploy

One time:

git remote add dokku [email protected]:titaniumsdk.com

Then to release:

git push dokku main

Contributions

Open source contributions are greatly appreciated! If you have a bugfix, improvement or new feature, first make sure you have signed the TiDev CLA, then create an issue first and submit a pull request against master.

Legal

Titanium is a registered trademark of TiDev Inc. All Titanium trademark and patent rights were transferred and assigned to TiDev Inc. on 04/07/2022. Please see the LEGAL information about using our trademarks, privacy policy, terms of usage and other legal information at https://tidev.io/legal.

License

Titanium is licensed under the OSI approved Apache Public License (Version 2). All trademark rights were assigned to TiDev, Inc. on 04/07/2022 from Axway, Inc. Please see the LICENSE file for more details.