Merge pull request #30 from 10up/enhancement/17

Added Developer Documentation site (hookdocs integration)
10up · Jan 4, 2023 · a5e02be · a5e02be
2 parents ec85fc3 + 63237da
commit a5e02be
Show file tree

Hide file tree

Showing 13 changed files with 778 additions and 7 deletions.
diff --git a/.distignore b/.distignore
@@ -8,14 +8,18 @@
 .distignore
 .editorconfig
 .gitignore
+.nvmrc
 CHANGELOG.md
 CODE_OF_CONDUCT.md
 composer.json
 composer.lock
 CONTRIBUTING.md
 CREDITS.md
+hookdoc-conf.json
 LICENSE.md
+package.json
+package-lock.json
 phpcs.xml
 phpunit.xml
 phpunit.xml
-README.md
+README.md
diff --git a/.github/hookdoc-tmpl/README.md b/.github/hookdoc-tmpl/README.md
@@ -0,0 +1,9 @@
+# Simple Google News Sitemap Developer Documentation
+
+This resource is generated documentation on actions, filters, and WP-CLI commands found in the Simple Google News Sitemap plugin. Use the sidebar to browse and navigate.
+
+For more information about using Simple Google News Sitemap with WordPress, please see the documentation [here](https://github.com/10up/simple-google-news-sitemap#usage).
+
+To report an issue with Simple Google News Sitemap or contribute back to the project, please visit the [GitHub repository](https://github.com/10up/simple-google-news-sitemap/).
+
+<a href="http://10up.com/contact/" class="banner"><img src="https://10updotcom-wpengine.s3.amazonaws.com/uploads/2016/10/10up-Github-Banner.png" width="850"></a>
diff --git a/.github/hookdoc-tmpl/layout.tmpl b/.github/hookdoc-tmpl/layout.tmpl
@@ -0,0 +1,46 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="utf-8">
+    <title><?js= title ?> - 10up Simple Google News Sitemap Hook Docs</title>
+
+    <script src="scripts/prettify/prettify.js"> </script>
+    <script src="scripts/prettify/lang-css.js"> </script>
+    <!--[if lt IE 9]>
+      <script src="//html5shiv.googlecode.com/svn/trunk/html5.js"></script>
+    <![endif]-->
+    <link type="text/css" rel="stylesheet" href="styles/prettify-tomorrow.css">
+    <link type="text/css" rel="stylesheet" href="styles/jsdoc-default.css">
+
+	<link href="https://fonts.googleapis.com/css?family=IBM+Plex+Mono|IBM+Plex+Sans:300,400|Playfair+Display:900&display=swap" rel="stylesheet">
+    <link type="text/css" rel="stylesheet" href="styles-10up.css">
+</head>
+
+<body<?js if (title === 'Home') { ?> class="home"<?js } ?>>
+
+<div id="main">
+
+	<?js if (title !== 'Home') { ?>
+    <h1 class="page-title"><?js= title ?></h1>
+	<?js } ?>
+
+    <?js= content ?>
+
+    <footer>
+		<a href="https://github.com/10up/simple-google-news-sitemap/">Simple Google News Sitemap on GitHub</a> &bull;
+		<a href="https://10up.com/careers">Careers at 10up</a>
+	</footer>
+
+
+</div>
+
+<nav>
+    <?js= this.nav ?>
+</nav>
+
+<br class="clear">
+
+<script> prettyPrint(); </script>
+<script src="scripts/linenumber.js"> </script>
+</body>
+</html>
diff --git a/.github/hookdoc-tmpl/static/styles-10up.css b/.github/hookdoc-tmpl/static/styles-10up.css
@@ -0,0 +1,136 @@
+body {
+	background: #fefefe;
+	color: #232323;
+	font-family: 'IBM Plex Sans', sans-serif;
+	font-size: 1.3rem;
+	font-weight: 300;
+}
+
+h1, h2, h3 {
+	line-height: 1.2;
+	font-family: 'Playfair Display', sans-serif;
+	font-weight: 900;
+	letter-spacing: -.01em;
+}
+
+h1.page-title {
+	font-size: 42px;
+	margin-top: .5em;
+}
+
+nav {
+	display: flex;
+	flex-direction: column;
+}
+
+nav * {
+	order: 4;
+}
+
+nav h2 {
+	order: 1;
+}
+
+nav h3:nth-of-type(3) {
+	order: 2;
+	visibility: hidden;
+	position: relative;
+}
+
+nav h3:nth-of-type(3):after {
+	content: 'Docs';
+	visibility: visible;
+	position: absolute;
+	left: 0;
+}
+
+nav ul:nth-of-type(3) {
+	order: 3;
+}
+
+nav ul {
+	font-size: 1.2rem;
+}
+
+nav li a {
+	background-image: none;
+}
+
+nav li a:hover {
+	text-decoration: underline;
+}
+
+code, pre,
+nav ul a, nav ul a:visited, nav ul a:active,
+.name, .signature,
+.params .name, .props .name,
+.name code {
+	font-family: 'IBM Plex Mono', monospace;
+}
+
+article h1 {
+	margin: 12px 0 32px;
+}
+
+a {
+	background-image: linear-gradient(transparent calc(100% - 7px), #f2dede 0),
+	linear-gradient(transparent calc(100% - 7px), #cef8f7 0);
+	background-position: 0 0;
+	background-repeat: no-repeat;
+	background-size: 0 100%, 100% 100%;
+	color: #232323;
+	text-decoration: none;
+	transition: all .1s;
+}
+
+a:visited,
+a:active {
+	color: #232323;
+}
+
+a:focus,
+a:hover {
+	background-size: 100% 100%, 100% 100%;
+	color: #232323;
+	text-decoration: none;
+}
+
+a.banner {
+	background-image: none;
+	margin-left: -10px;
+}
+
+a.banner img {
+	width: 100%;
+	max-width: 888px;
+}
+
+article img {
+	width: 100%;
+	max-width: 888px;
+	height: auto;
+	margin: 15px 0;
+}
+
+footer {
+	text-align: center;
+	font-size: .8em;
+	font-style: normal;
+	font-weight: 300;
+}
+
+.home #main > section:first-of-type,
+.home nav > h2 {
+	display: none;
+}
+
+.prettyprint.source {
+	font-size: 14px;
+}
+
+.prettyprint code {
+	padding: 2px 10px;
+	line-height: 16px;
+	min-height: 16px;
+	height: auto;
+}
diff --git a/.github/workflows/build-docs.yml b/.github/workflows/build-docs.yml
@@ -0,0 +1,29 @@
+name: Build Hook Docs
+
+on:
+ push:
+   branches:
+    - trunk
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v3
+    - name: Use desired version of NodeJS
+      uses: actions/setup-node@v3
+      with:
+          node-version-file: '.nvmrc'
+
+    - name: Install dependencies and Generate docs
+      run: |
+        npm install
+        npm run build:docs
+      env:
+        CI: true
+
+    - name: Deploy to GH Pages
+      uses: peaceiris/actions-gh-pages@v3
+      with:
+        github_token: ${{ secrets.GITHUB_TOKEN }}
+        publish_dir: './docs'
diff --git a/.gitignore b/.gitignore
@@ -6,3 +6,9 @@
 
 # Cache files
 *.cache
+
+# npm packages
+/node_modules/
+
+# Hookdoc generated files
+/docs/
diff --git a/.nvmrc b/.nvmrc
@@ -0,0 +1 @@
+v16
diff --git a/hookdoc-conf.json b/hookdoc-conf.json
@@ -0,0 +1,25 @@
+{
+  "opts": {
+      "destination": "docs",
+      "template": "node_modules/wp-hookdoc/template",
+      "recurse": true,
+      "readme": "./.github/hookdoc-tmpl/README.md"
+  },
+  "source": {
+      "includePattern": ".+\\.(php|inc)?$"
+  },
+  "plugins": [
+    "node_modules/wp-hookdoc/plugin",
+    "plugins/markdown"
+  ],
+  "templates":  {
+    "default": {
+      "layoutFile": ".github/hookdoc-tmpl/layout.tmpl",
+      "staticFiles": {
+        "include": [
+          "./.github/hookdoc-tmpl/static"
+        ]
+      }
+    }
+  }
+}
diff --git a/includes/classes/Core.php b/includes/classes/Core.php
@@ -187,7 +187,9 @@ public function purge_sitemap_data_on_status_change( string $new_status, string
 		 *
 		 * @since 1.0.0
 		 *
-		 * @param array $post_statuses Post statuses we clear cache on.
+		 * @hook simple_google_news_sitemap_post_statuses_to_clear
+		 * @param {array} $post_statuses Post statuses we clear cache on.
+		 * @returns {array} Filtered post statuses.
 		 */
 		$post_statuses = apply_filters( 'simple_google_news_sitemap_post_statuses_to_clear', $post_statuses );
 
@@ -218,7 +220,9 @@ public function ping_google(): bool {
 		 *
 		 * @since 1.0.0
 		 *
-		 * @param boolean $should_ping Should we ping Google? Default true.
+		 * @hook simple_google_news_sitemap_ping
+		 * @param {boolean} $should_ping Should we ping Google? Default true.
+		 * @returns {boolean} Should we ping Google?
 		 */
 		if ( false === apply_filters( 'simple_google_news_sitemap_ping', true ) ) {
 			return false;

diff --git a/includes/classes/Sitemap.php b/includes/classes/Sitemap.php
@@ -74,7 +74,9 @@ public function supported_post_types(): array {
 		 *
 		 * @since 1.0.0
 		 *
-		 * @param array $post_types List of post types to support.
+		 * @hook simple_google_news_sitemap_post_types
+		 * @param {array} $post_types List of post types to support.
+		 * @returns {array} List of post types to support.
 		 */
 		return apply_filters( 'simple_google_news_sitemap_post_types', $post_types );
 	}
@@ -115,8 +117,10 @@ public function build() {
 					 *
 					 * @since 1.0.0
 					 *
-					 * @param array  $item The item that will be displayed.
-					 * @param string $post_type The post type of the item.
+					 * @hook simple_google_news_sitemap_post
+					 * @param {array}  $item The item that will be displayed.
+					 * @param {string} $post_type The post type of the item.
+					 * @returns {array} The item that will be displayed.
 					 */
 					$item = apply_filters( 'simple_google_news_sitemap_post', $item, $post_type );
 

diff --git a/includes/templates/google-news-sitemap.php b/includes/templates/google-news-sitemap.php
@@ -14,7 +14,9 @@
  *
  * @since 1.0.0
  *
- * @param array $links Array of items to be output.
+ * @hook simple_google_news_sitemap_data
+ * @param {array} $links Array of items to be output.
+ * @returns {array} Array of items to be output.
  */
 $links = apply_filters( 'simple_google_news_sitemap_data', $links );
 
@@ -37,6 +39,7 @@
 	 * Add extra data to the start of the sitemap.
 	 *
 	 * @since 1.0.0
+	 * @hook simple_google_news_sitemap_start
 	 */
 	do_action( 'simple_google_news_sitemap_start' );
 
@@ -68,6 +71,7 @@
 	 * Add extra data to the end of the sitemap.
 	 *
 	 * @since 1.0.0
+	 * @hook simple_google_news_sitemap_end
 	 */
 	do_action( 'simple_google_news_sitemap_end' );
 	?>