Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

feature: jsdoc annotations and generation #177

Merged
merged 1 commit into from
Oct 3, 2023
+3,116 −78
Merged

feature: jsdoc annotations and generation #177

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
289 changes: 262 additions & 27 deletions .gitignore
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,58 @@
# Created by https://www.toptal.com/developers/gitignore/api/intellij
# Edit at https://www.toptal.com/developers/gitignore?templates=intellij
# Created by https://www.toptal.com/developers/gitignore/api/intellij+all,node,vim,emacs,macos
# Edit at https://www.toptal.com/developers/gitignore?templates=intellij+all,node,vim,emacs,macos
Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Annotation:
gitignore changes are primarily to take care of the new nodejs depenedency for docs builds.


### Intellij ###
### Emacs ###
# -*- mode: gitignore; -*-
*~
\#*\#
/.emacs.desktop
/.emacs.desktop.lock
*.elc
auto-save-list
tramp
.\#*

# Org-mode
.org-id-locations
*_archive

# flymake-mode
*_flymake.*

# eshell files
/eshell/history
/eshell/lastdir

# elpa packages
/elpa/

# reftex files
*.rel

# AUCTeX auto folder
/auto/

# cask packages
.cask/
dist/

# Flycheck
flycheck_*.el

# server auth directory
/server/

# projectiles files
.projectile

# directory configuration
.dir-locals.el

# network security
/network-security.data


### Intellij+all ###
# Covers JetBrains IDEs: IntelliJ, RubyMine, PhpStorm, AppCode, PyCharm, CLion, Android Studio, WebStorm and Rider
# Reference: https://intellij-support.jetbrains.com/hc/en-us/articles/206544839

Expand All @@ -12,6 +63,9 @@
.idea/**/dictionaries
.idea/**/shelf

# AWS User-specific
.idea/**/aws.xml

# Generated files
.idea/**/contentModel.xml

Expand Down Expand Up @@ -53,6 +107,12 @@ cmake-build-*/
# IntelliJ
out/

# jsdoc build directory
reference/
Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Annotation:
This is added to ignore the built documentation.


# minio storage
data/

# mpeltonen/sbt-idea plugin
.idea_modules/

Expand All @@ -62,6 +122,9 @@ atlassian-ide-plugin.xml
# Cursive Clojure plugin
.idea/replstate.xml

# SonarLint plugin
.idea/sonarlint/

# Crashlytics plugin (for Android Studio and IntelliJ)
com_crashlytics_export_strings.xml
crashlytics.properties
Expand All @@ -74,37 +137,209 @@ fabric.properties
# Android studio 3.1+ serialized cache file
.idea/caches/build_file_checksums.ser

### Intellij Patch ###
# Comment Reason: https://github.com/joeblau/gitignore.io/issues/186#issuecomment-215987721
### Intellij+all Patch ###
# Ignore everything but code style settings and run configurations
# that are supposed to be shared within teams.

.idea/*

!.idea/codeStyles
!.idea/runConfigurations

### macOS ###
# General
.DS_Store
.AppleDouble
.LSOverride

# Icon must end with two \r
Icon


# Thumbnails
._*

# Files that might appear in the root of a volume
.DocumentRevisions-V100
.fseventsd
.Spotlight-V100
.TemporaryItems
.Trashes
.VolumeIcon.icns
.com.apple.timemachine.donotpresent

# Directories potentially created on remote AFP share
.AppleDB
.AppleDesktop
Network Trash Folder
Temporary Items
.apdisk

### macOS Patch ###
# iCloud generated files
*.icloud

### Node ###
# Logs
logs
*.log
npm-debug.log*
yarn-debug.log*
yarn-error.log*
lerna-debug.log*
.pnpm-debug.log*

# Diagnostic reports (https://nodejs.org/api/report.html)
report.[0-9]*.[0-9]*.[0-9]*.[0-9]*.json

# Runtime data
pids
*.pid
*.seed
*.pid.lock

# Directory for instrumented libs generated by jscoverage/JSCover
lib-cov

# Coverage directory used by tools like istanbul
coverage
*.lcov

# nyc test coverage
.nyc_output

# Grunt intermediate storage (https://gruntjs.com/creating-plugins#storing-task-files)
.grunt

# Bower dependency directory (https://bower.io/)
bower_components

# node-waf configuration
.lock-wscript

# Compiled binary addons (https://nodejs.org/api/addons.html)
build/Release

# Dependency directories
node_modules/
jspm_packages/

# Snowpack dependency directory (https://snowpack.dev/)
web_modules/

# TypeScript cache
*.tsbuildinfo

# Optional npm cache directory
.npm

# Optional eslint cache
.eslintcache

# Optional stylelint cache
.stylelintcache

# Microbundle cache
.rpt2_cache/
.rts2_cache_cjs/
.rts2_cache_es/
.rts2_cache_umd/

# Optional REPL history
.node_repl_history

# Output of 'npm pack'
*.tgz

# Yarn Integrity file
.yarn-integrity

# dotenv environment variable files
.env
.env.development.local
.env.test.local
.env.production.local
.env.local

# parcel-bundler cache (https://parceljs.org/)
.cache
.parcel-cache

# Next.js build output
.next
out

# Nuxt.js build / generate output
.nuxt
dist

# Gatsby files
.cache/
# Comment in the public line in if your project uses Gatsby and not Next.js
# https://nextjs.org/blog/next-9-1#public-directory-support
# public

# vuepress build output
.vuepress/dist

# vuepress v2.x temp and cache directory
.temp

# Docusaurus cache and generated files
.docusaurus

# Serverless directories
.serverless/

# FuseBox cache
.fusebox/

# DynamoDB Local files
.dynamodb/

# TernJS port file
.tern-port

# Stores VSCode versions used for testing VSCode extensions
.vscode-test

# yarn v2
.yarn/cache
.yarn/unplugged
.yarn/build-state.yml
.yarn/install-state.gz
.pnp.*

*.iml
modules.xml
.idea/misc.xml
*.ipr
### Node Patch ###
# Serverless Webpack directories
.webpack/

# Sonarlint plugin
# https://plugins.jetbrains.com/plugin/7973-sonarlint
.idea/**/sonarlint/
# Optional stylelint cache

# SonarQube Plugin
# https://plugins.jetbrains.com/plugin/7238-sonarqube-community-plugin
.idea/**/sonarIssues.xml
# SvelteKit build / generate output
.svelte-kit

# Markdown Navigator plugin
# https://plugins.jetbrains.com/plugin/7896-markdown-navigator-enhanced
.idea/**/markdown-navigator.xml
.idea/**/markdown-navigator-enh.xml
.idea/**/markdown-navigator/
### Vim ###
# Swap
[._]*.s[a-v][a-z]
!*.svg # comment out if you don't need vector files
[._]*.sw[a-p]
[._]s[a-rt-v][a-z]
[._]ss[a-gi-z]
[._]sw[a-p]

# Cache file creation bug
# See https://youtrack.jetbrains.com/issue/JBR-2257
.idea/$CACHE_FILE$
# Session
Session.vim
Sessionx.vim

# CodeStream plugin
# https://plugins.jetbrains.com/plugin/12206-codestream
.idea/codestream.xml
# Temporary
.netrwhist
# Auto-generated tag files
tags
# Persistent undo
[._]*.un~

# End of https://www.toptal.com/developers/gitignore/api/intellij
# End of https://www.toptal.com/developers/gitignore/api/intellij+all,node,vim,emacs,macos

# Test data files
test-settings.*
Expand Down
1 change: 1 addition & 0 deletions .tool-versions
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
nodejs 20.8.0
27 changes: 27 additions & 0 deletions GNUmakefile
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -22,3 +22,30 @@ help:
.PHONY: test
test: ## Run all tests
$Q $(CURDIR)/test.sh --type oss --unprivileged false --latest-njs false

# Check if the 'open' command exists on the system
OPEN := $(shell command -v open 2> /dev/null)

# Define the open command based on availability
ifeq ($(OPEN),)
OPEN_COMMAND = xdg-open
else
OPEN_COMMAND = open
endif

docs_destination_directory = "reference"

.PHONY: docs
Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Annotation:
This may not be the correct thing to do, but without it I could not get the make jsdoc make clean make jsdoc flow to work correctly.

I figure it's safer to build the docs every time anyway. In a CI context this shouldn't matter.

docs:
npx jsdoc -c $(CURDIR)/jsdoc/conf.json -d $(CURDIR)/$(docs_destination_directory) || true

.PHONY: jsdoc
jsdoc: docs ## Build JSDoc output

.PHONY: jsdoc-open
jsdoc-open: docs
$(OPEN_COMMAND) $(CURDIR)/$(docs_destination_directory)/index.html

.PHONY: clean
clean: ## Clean up build artifacts
$Q rm -rf $(CURDIR)/$(docs_destination_directory)
4 changes: 3 additions & 1 deletion README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -68,6 +68,7 @@ deployments/ contains files used for deployment technologies
docs/ contains documentation about the project
examples/ contains additional `Dockerfile` examples that extend the base
configuration
jsdoc JSDoc configuration files
oss/ contains files used solely in NGINX OSS configurations
plus/ contains files used solely in NGINX Plus configurations
test/ contains automated tests for validang that the examples work
Expand All @@ -79,9 +80,10 @@ Dockerfile.buildkit.plus Dockerfile with the same configuration as Docke
with support for hiding secrets using Docker's Buildkit
Dockerfile.latest-njs Dockerfile that inherits from the last build of the gateway and
then builds and installs the latest version of njs from source
Dockerfile.unprivileged Dockerfiles that inherits from the last build of the gateway and
Dockerfile.unprivileged Dockerfiles that inherits from the last build of the gateway and
makes the necessary modifications to allow running the container
as a non root, unprivileged user.
package.json Node.js package file used only for generating JSDoc
settings.example Docker env file example
standalone_ubuntu_oss_install.sh install script that will install the gateway as a Systemd service
test.sh test launcher
Expand Down
Loading
Loading