BioLockJ Developers Guide#

Release process#

Release process

Javadocs#

https://BioLockJ-Dev-Team.github.io/BioLockJ/javadocs/

Guidelines for new modules#

Building Modules

How to edit the user guide#

The source material for the user guide is under $BLJ/mkdocs/user-guide/ . Part of the release process is using mkdocs to produce the html user-guide from these pages. The html form is stored under $BLJ/docs. readthedocs.org looks at the git repository and finds the mkdocs/docs folder to build the user-guide hosted on readthedocs.org. GitHubPages looks at the git repository and finds the /docs folder and hosts those pages.

The pages under $BLJ/mkdocs/user-guide/docs are edited manually EXCEPT files under the "GENERATED" folder. These files are generated by the biolockj.api.BuildDocs class so that they are updated each time the jar file is built for release. The generated pages include the user-guide page for each module (completely generated from the module info), and several hybrid pages that include the current options recognized by BioLockJ and a manually written description section. The manual section is stored in $BLJ/mkdocs/user-guide/partials/ , and is often divided bewteen a header and footer, which appear above and below the java-generated section.

The pages under $BLJ/mkdocs/user-guide/docs/module will eventually be removed. To edit how all modules info is displayed, edit the BuildDocs class (this should rarely be the case). To edit the user-guide page for a module, you'll have to update the relevant methods in that module, such getDescription() or getDetails(). To create a details section with long prose and md formatting, you can create a .md file with the formatted text, and reference that file in the getDetails() method. For example, the GenMod module page has a lengthy "Details" section, and its getDetails() method looks like this:

    @Override
    public String getDetails() throws API_Exception {
        return BuildDocs.copyFromModuleResource( this, "GenModDetails.md" );
    }

Where the file GenModDetails.md is included in the jar file as a resource. For more information about how to use module methods to document a module, see "Document your module" on the Building Modules page.

To reflect changes in java code in the md files under "GENERATED", run:

cd ${BLJ}/resources
ant userguide

To view the updated docs in their fully formatted form, create a server hosting the user-guide for your web browser. To do this, run:

cd ${BLJ}/mkdocs/user-guide
mkdocs serve

This prints a message with a local host address; paste that into your web browser. This will reflect realtime changes to all of the md files under docs/.

You can also set up GitHub Pages for your own fork of BioLockJ to mimic the main BioLockJ Pages. Then you can commit changes to the html files and view them as they will be displayed via GitHub pages. This is more work, and only beneficial if you are making novel layout/formatting changes and you want to make sure they are displayed correctly, or if you want to make it easy for someone else to review your documentation changes without having to checkout and build your development branch.

When committing changes, you only need to commit the file where you edited text. In the release process, render all docs, and commit the GENERATED md files, and the /docs/*.html files.