docsforadobe.dev

by

https://docsforadobe.dev

Hosted at	https://.docsforadobe.dev/
Repository	https://github.com/docsforadobe/docsforadobe.dev
Copyright	All content is copyright Adobe Systems Incorporated.

Contribution Guide¶

This endeavour is primarily community-supported & run; contributors are welcome and encouraged to suggest fixes, adjustments, notes/warnings, and anything else that may help the project.

This project is written in Markdown, styled & served using mkdocs.

Build HTML Locally¶

Before pushing to the online project (or submitting a PR), we ask that you develop & test the project locally to ensure the result is what you'd expect.

To build locally:

Install python & pip
From a terminal, navigate to the project directory and run the following command to install dependencies:
```
pip install -r requirements.txt
```
When done, run the following command to serve the docs:
```
mkdocs serve
```
Open your browser to the provided url (http://127.0.0.1:8000) by default to view the live-updating docs

Admonitions Usage¶

Currently, the following admonitions are in use in this project. Try to keep one piece of data per note, for easier parsing.

!!! note
    Notes detail version added, and/or relevant pieces of information.

!!! tip
    Tips detail version added, and/or relevant pieces of information.

!!! warning
    Warnings convey negative behaviours, or when something won't work the way you'd expect.

These will render as:

Note

Notes detail version added, and/or relevant pieces of information.

Tip

Tips detail version added, and/or relevant pieces of information.

Warning

Warnings convey negative behaviours, or when something won't work the way you'd expect.

Adding undocumented attributes or methods¶

If you find attributes or methods that are not mentioned in this documentation, and they are not publically announced by Adobe, please add this warning to attribute/method so the user knows to use it at their own risk.

!!! warning
    This method/property is officially undocumented and was found via research. The information here may be inaccurate, and this whole method/property may disappear or stop working some point. Please contribute if you have more information on it!

Rendered as:

Warning

This method/property is officially undocumented and was found via research. The information here may be inaccurate, and this whole method/property may disappear or stop working some point. Please contribute if you have more information on it!

Licensing & Ownership¶

This project exists for educational purposes only.

All content is copyright Adobe Systems Incorporated.

Updating Legacy Docs ↵

.rst -> MD Conversion Process¶

This is a one-time conversion process; it requires changing the Sphinx build system, building as markdown, replacing all the older rst files with the new markdown files, and then going through and cleaning up by hand.
It is tedious, but the bulk of the work is cleaning vs actual conversion– and we can leverage the existing Sphinx setup.
This relies on the sphinx_markdown_builder Sphinx plugin.

Tip

It is highly recommended to do this work in a child branch of the repo, vs working directly in main. This will be extremely destructive.

This works in several main phases:

Setup – installing required systems for the automated conversion
Convert – running these systems to convert the .rst docs to .md
Initialize Mkdocs – set up the new system that will serve the files
Text Cleanup – all of the work to turn the converted docs to a final product
Project Cleanup – removing the legacy build system files
Deploy

1. Setup¶

First, all work should be done in a new branch. Historically, these have been named change/mkdocs.

Once the work is done, submit a PR to merge it into the main branch.

Setting up RST -> MD Conversion¶

Install sphinx & sphinx_markdown_builder (for converting from .rst to .md):
```
pip install sphinx sphinx_markdown_builder
```
Update Sphinx config to convert to Markdown
- Navigate to ./docs/conf.py
- Replace all of the contents with only this:
```
extensions = ["sphinx_markdown_builder"]
```

Setting up the new system¶

Replace all contents of ./requirements.txt with the following list of dependencies:

mkdocs
mkdocs-material
mkdocs-git-revision-date-localized-plugin
mkdocs-print-site-plugin

Install the above requirements via pip:
```
pip install -r requirements.txt
```

2. Convert¶

Run the sphinx command to convert the docs
```
sphinx-build -M markdown ./docs ./build
```
- This will generate .md files within ./build/markdown
We want to replace all of the .rst files with the .md files, however if we simply delete the .rst and add the .md we will lose all of the git history!
To get around this, we're going to first rename all of the .rst files to .md, and then overwrite the "fake" renamed .md files with the converted .md files
Using your renamer tool of choice, rename all .rst files in docs/ to the .md extension
Commit this rename change!
Be careful not to commit anything in ./build/, as we don't want these in the repo (yet)
Now, overwrite all ./docs/ .md files with those from ./build/markdown/
Delete the ./build/ folder, as it won't be needed
Rename ./docs/index.md to ./docs/_nav.md
This is a temporary process that we'll resolve later
It needs to be rewritten in a different format, and moved into ./mkdocs.yml, with this file deleted
Commit this overwrite change!
This solidifies the history, at which point we can start cleanup

3. Initialize Mkdocs¶

Instead of initializing Mkdocs from scratch, we're going to just copy files over from the After Effects Scripting Guide and tweak those to fit.

Copy the following files from the above guide into this repo, overwriting if existing:
- ./.github/
- ./_static/
- ./docs/CNAME
- ./docs/index.md
- ./overrides/
- ./.editorconfig
- ./.gitattributes
- ./.gitignore
- ./.mkdocs.yml
Update anything related to "After Effects Scripting Guide" and make it relevant for this repo
- ./docs/index.md
- ./.mkdocs.yml
Open a terminal to the root folder, and run the below command to serve the docs
```
mkdocs serve
```

4. Text Cleanup¶

Bulk Cleanup¶

Search & Replace Steps¶

Remove generated <a> links
- Using regex, search for <a id=".+"></a>(\n|\r)(\n|\r) and replace with blank
Update notes, warnings, tips admonitions
- Valid admonitions can be found here
- Using regex, search for #### NOTE\n(.+) and replace with !!! note\n $1
- Using regex, search for #### WARNING\n(.+) and replace with !!! warning\n $1
- Using regex, search for #### TIP\n(.+) and replace with !!! tip\n $1
Update case-sensitive syntax highlighting languages
- Using regex, search for ```AppleScript and replace with ```applescript
Replace nonstandard
- Using regex, search for “|” and replace with "
- Using regex, search for ‘|’ and replace with '
- Using regex, search for – and replace with -
- Search for … and replace with ...
Update offset sublist settings
- Using regex, search for(\n|\r) : - and replace with :\n - – only seems to be an issue with changelog

Look for lingering bulk-conversion issues¶

Search for lines starting with : - and
Search for rst-specific syntax such as the below, and fix them as needed
- .. note::
- ::
- :ref:
- .. WARNING::

Manual Cleanup¶

The sidebar / navigation needs to be present inside of ./mkdocs.yml, formatted identically to how it's presented in the After Effects Scripting Guide repo.

Earlier, we set aside ./docs/_nav.md as a reference point. Now, use that file as the basis for how to display the nav within the nav section within ./mkdocs.yml.

When finished, delete ./docs/_nav.md.

Links¶

Search for hyphenated cross-links and replace with plain slugs, i.e.
- [CharacterRange.pasteFrom()](../text/characterrange.md#characterrange-pastefrom) to
- [CharacterRange.pasteFrom()](../text/characterrange.md#characterrangepastefrom)
- This regex search can help, but fails when the link is also a header (see changelog):
- (?:#)(.*?)-(.*?)(?:\)) => #$1$2)
Search for anchored links to the top-level page & replace with direct page link, i.e.
- [Settings object](../other/settings.md#settings) to
- [Settings object](../other/settings.md)
- This regex search / replace can help:
- (.*)\.md#(\1)\) => $1.md)
Search for empty in-page links and replace them with the proper format, i.e.
- [app.watchFolder()]() to
- [app.watchFolder()](#appwatchfolder)

Update Tables¶

In RST, tables didn't need to have header rows. In markdown, they do (should). This, unfortunately, means a lot of work is needed as the conversion method isn't capable of generating table headers.

Note

We're also going to use this opportunity to add in property types for arguments & parameters, making the docs friendlier to use.

Set up table headers (see below)
Remove any html linebreaks (<br>) unless explicitly required – this is very rare, but sometimes does occur
Format tables

Here are the table header formats to use:

Function parameters

| Parameter | Type | Description |
| --------- | ---- | ----------- |

Returned objects

| Property | Type | Description |
| -------- | ---- | ----------- |

Titles¶

# Page
## Category ("Attributes", "Methods")
### Attribute/Method Name ("CharacterRange.characterEnd")
#### Info Header ("Description", "Type", "Parameters", "Returns")

Other¶

Check that images are properly linked to the root ./docs/_static folder
Value ranges should be formatted as: `[0.0..10800.0]` (surrounded by backticks, two periods between min and max)

5. Project Cleanup¶

Now that we've got a full suite of .md files, we can remove some old cruft:

./build/
./docs/**/*.rst
./docs/conf.py
./.readthedocs.yaml
./make.bat
./Makefile

6. Open a PR!¶

Once the above steps are complete, it's time to open a PR for review!

Open a new Pull Request for merging the change/mkdocs branch into the main branch of the repo.

Once reviewed & accepted by an org admin, your converted docs will be pushed into main repo and it'll be time for an org admin to Deploy the docs!

Deploying the Updated Docs¶

Tip

Note that the following guide is only possible for Org admins. If you're stuck at this step, please contact an organization admin to proceed.

Once a conversion-branch PR has been approved & merged into the main repo, it's time to deploy the new docs.

Once the PR has been merged in, the automated build process (from .\github\workflows\ci.yml) should run, generating a new branch gh-pages. This is the branch we'll use to generate the hosted page via Github Pages.

Changes in the Repo¶

Update the ./docs/CNAME file to reflect the new custom domain (ie ae-scripting.docsforadobe.dev -> ai-scripting.docsforadobe.dev) & ensure this change is committed & pushed
- If this isn't committed to the main branch, then every push to the repo (and CI action) will remove this file and lose the custom domain. See this gh-pages issue.

Changes on Github¶

From the Github repo, set up Pages & have it use this new branch.
- Settings > Pages > Enable Pages
- Deploy from a Branch > Choose the named branch above
- For folder, choose "/ (root)"
Set up the custom domain (xx.docsforadobe.dev)
- This may already be defined by the above CNAME file, but check here just in case.
- Enable "Enforce HTTPs"

Changes on web host¶

In the domain registrar / web host, enable DNS-only hosting for this domain
Add a CNAME record pointing to docsforadobe.github.io
Apply for an SSL cert
Remove any readthedocs.io hooks from the Github repo
Set up branch permissions to require PRs to the main branch

Changes in readthedocs.io¶

Remove the legacy docs from readthedocs.io

Ended: Updating Legacy Docs