Advanced Topics

In the main plugins directory there are four important files:

When we make a local build of the plugins manual or use a script from Github Workflow the following is executed: antora site.yml. For a local build the HTML is found in the docs directory. The website can be started by opening 'index.html'.

The first two lines of this file (at the present time) are:

Space separated items on each line. The first item is the name of the plugin. Second item the git clone URL. Third item is the commit being used for the OpenCPN plugins manual.

sources.state is a sorted alphabetical list of all the plugins available, master and beta combined.

This script has three main arguments:

copies state from sources.state → sources directory

updates sources

copies state from sources → sources.state file

"state" is the commit that is used for the manual.

source-state restore is run before a local build to ensure all the plugin directories in the sources directory contain the manuals from the plugins listed in sources.state. This script is also run as part of the script building the website using Github Actions.

The build-and-deploy.sh script in the ci directory shows $source-state restore being used.

New commits to the dev plugin manuals will have been made since sources.state was last compiled. source-state update, run locally, 'visits' each plugin in the sources directory and if a new commit has been made updates the data for the plugin, in the 'sources' directory. It has not changed the data in sources.state.

A local build would then use the latest dev plugin commit, but if the website is built by Github Actions the existing (old) sources.state file is used.

In this way the state of the plugins manual can be tracked, by the commits made to the OpenCPN plugins manual. So far nothing has changed the state of the repository.'.gitignore' prevents any local build docs files or sources files being committed to the repository.

When the latest commits of all the plugins are needed source-state save is run. This copies the commit hashes from the plugin sources and updates the sources.state file. The next commit for the OpenCPN plugins manual will use the new dev plugin commits, if any.

In addition an individual plugin manual can be added to sources and the sources.state file updated:

Where [plugin…​] is the URL for the plugin. The plugin has to be already listed in sources.state.

This will not normally be handled by the developer but by a maintainer of the OpenCPN Plugins Manual.

A build of the OpenCPN Plugins Manual needs to locate and use the dev plugin repository. sources.state holds the data for the plugins and a new entry is needed in the list. Keep the list sorted!

Asciidoc nav- files in the partials directory are used to create lists of the plugins, which appear on the left hand side of the website page. They duplicate other lists but they are essential for the indexing of the different individual dev plugin manuals.

There is one component in the manual, plugins. On the website it is possible to navigate the plugins component. Each component can have a number of modules. ROOT is an important module that contains the nav.adoc page that provides the link with the plugin pages. Nav.adoc is comprised of the partials directory files nav-main.adoc, nav-beta.adoc and nav-all.adoc which are used to construct the left hand navigation bars, which are edited as necessary.

As an example the following lines were added when DR_pi was added to the master plugins:

The indenting is important. Follow the indenting already in use.

Editing to add or remove a plugin from the index is done in the partials folder, because these files are "included" in both the left side navigation and the center display. Because we are working with a main plugin that has been released, the files nav-main.adoc and nav-all.adoc are edited. (The file nav-beta.adoc is edited for beta plugins. Authoring and General and Supplementary Information changes may require index changes in those sections but that is normally done by maintainers.)

'nav-main.adoc' is in the 'partials' directory of 'ROOT'. It contains a list of the main plugins displayed as part of nav.adoc (left side navigation) and is also "included" in the index-main.adoc file which shows at the center panel.

'nav-main.adoc' is in the 'partials' directory and is used for left side navigation index and is included with index-main.adoc file which shows at the center.

'nav-all.adoc' is in the 'partials' directory and is an alphabetical list, appearing on the left hand side of the pages.

Important: notice the reference 'dead_reckoning' is used and not DR for this plugin. This is the same text as entered for the title in the 'antora.yml' file in the dev plugin’s manual.

The whole OpenCPN Plugins Manual Github repository structure with only the DR_pi source shown: