applecommander.github.io

This site has moved to using the Material theme of MkDocs.

Setup

Note that MkDocs Material is breaking away from MkDocs due to a rewrite that causes issues. The requirements.txt file was introduced to lock this project into legacy versions that work together.

Generally follow the directions to get setup, but what was needed on Ubuntu Linux is only:

$ sudo apt install python3-pip python3-venv
$ python3 -m venv venv/
$ source venv/bin/activate
(venv) $ pip install -r requirements.txt

Developing

Git clone the site. Note that the branch working-copy is the primary branch to use. Since the applecommander.github.io is an organization page, content must be pushed on the master branch.

cd to the applecommander.github.io working directory and:

(venv) $ mkdocs serve

Open a browser to http://localhost:8000/ and the site will be there and can be live-edited.

Please note that the Javadoc section (docs/dev-notes/javadoc/) gives MkDocs fits, but it appears that the complaining can be safely ignored.

Javadocs

The included Makefile has a rule to use Gradle to build the corresponding documentation. It expects AppleCommander and ShrinkItArchive to be in the same directory as applecommander.github.io.

$ make javadoc
test -d ../AppleCommander
test -d ../ShrinkItArchive
(cd ../AppleCommander; ./gradlew javadoc)
Starting a Gradle Daemon (subsequent builds will be faster)

BUILD SUCCESSFUL in 2s
3 actionable tasks: 3 up-to-date
(cd ../ShrinkItArchive; ./gradlew javadoc)

BUILD SUCCESSFUL in 0s
2 actionable tasks: 2 up-to-date
rm -rf ./docs/dev-notes/javadoc/AppleCommander
mkdir -p ./docs/dev-notes/javadoc/AppleCommander
cp -r ../AppleCommander/build/docs/javadoc/* ./docs/dev-notes/javadoc/AppleCommander
rm -rf ./docs/dev-notes/javadoc/ShrinkItArchive
mkdir -p ./docs/dev-notes/javadoc/ShrinkItArchive
cp -r ../ShrinkItArchive/build/docs/javadoc/* ./docs/dev-notes/javadoc/ShrinkItArchive

Publishing

Any commit into the working-copy branch will be automatically published to the master branch by GitHub Actions.

The mkdocs.yml file has been configured to publish to master:

# Repository
remote_branch: master

Resources

• Material theme
• MkDocs