DEV Community 👩‍💻👨‍💻

David Hutchison
David Hutchison

Posted on • Originally published at devwithimagination.com on

Publishing a Compodoc Site to Nexus

Recently I have been looking at Compodoc for generating documentation sites for Angular projects. Some of these projects are for libraries that will be reused elsewhere, so this documentation requires to be published somewhere.

The libraries are published as NPM modules to a Sonatype Nexus instance, so it would be ideal if the documentation could be published to the same place.

Nexus has a Raw Repository type which can be used for hosting static websites. The linked page includes details of how to configure a repository, how to publish to it from Maven, and using curl to upload single files using HTTP requests.

Based on this curl approach I have put together a bash script below that:

  • has a number of configuration options for the user, nexus server, repository name, and documentation directory to upload
  • prompts for the password for the user to use
  • uses the git repository name as a subdirectory to store items in within the nexus repository, so that the same nexus repository could be used as a central location for generated documentation for multiple projects
  • iterates through every file in the configured documentation directory and uploads it to nexus

Once this script runs, you will be able to see the contents of the site in the browse view for the repository.

Repository browse view

Clicking on the index.html file will show the details, including the direct path to the artefact.

Index details

This will be the URL that your documentation site will be available at. The script below assumes there will be an index.html file and outputs the direct URL to this resource.

#!/bin/bash

# Configure username to use. The password will be prompted for later.
USER=admin

# The URL for the Nexus server
NEXUS_SERVER=https://nexus.example.com
# The name of the raw repository
REPOSITORY_NAME=documentation
# Each project will have its own directory based on the git repository name
GIT_REPO_NAME=$(basename -s .git $(git config --get remote.origin.url))

# Make our base Nexus repository directory URL
DEST_REPO_DIRECTORY="${NEXUS_SERVER}/repository/${REPOSITORY_NAME}/${GIT_REPO_NAME}"

# The directory to get the contents of to upload
LOCAL_DOCS=./documentation

# Prompt for the user password to use
read -s -p "Password for $USER: " PASS

# Find all the files in the directory and upload them. 
# This may have issues if you had spaces in filenames, but 
# generated documentation produced by compodoc doesn't

for file in $(find "$LOCAL_DOCS" -type f -print); do

    # Need to trim the local documentation directory part off the string
    destination_file="${file/$LOCAL_DOCS/}"

    # Upload the file
    # This uses verbose logging, you will want to reduce the logging here
    # if using this in a production environment
    curl -v --user "${USER}:${PASS}" --upload-file "$file" "${DEST_REPO_DIRECTORY}${destination_file}"

done

echo "If no errors were reported above, your documentation site will be available at ${DEST_REPO_DIRECTORY}/index.html"

Top comments (0)

🌚 Friends don't let friends browse without dark mode.

Sorry, it's true.