File structure (#28)

* first part

* added instructions to contributing

* add build and deploy badge to readme

* auto-alphebetize

* ncl applications

* move around applications structure

CONTRIBUTING.md

@@ -1,9 +1,33 @@
 # Contributor's Guide
 
-`conda env update -f environment.yml`
+## Create the docs locally
+``` python
+conda env update -f environment.yml
+conda activate geocat-applications
+make clean html
+open _build/html/index.html
+```
 
-`conda activate geocat-applications`
+## How to add entries or pages
+### Applications
+TO DO
 
-`make clean html`
+### NCL Index
+There are two paths to adding something to the NCL index:
+1. After creating a new applications entry
+2. Adding an entry that does not have a corresponding applications entry
 
-`open _build/html/index.html`
+#### After creating a new applications entry
+To add a new entry to the NCL Index after creating a new geocat-applications entry:
+1. Add a new line to the `ncl/ncl_index/ncl-index-table.csv` file
+
+#### Adding an entry that does not have a corresponding applications entry
+We include entries in the NCL Index that do not have corresponding geocat-applications entries for the purpose of
+including functions that are too small to warrant their own entry and to give users verified recommendations before
+an applications entry is completed.
+
+To add an entry that does not have a corresponding geocat-applications entry:
+1. Create a "receipt" file in the `ncl/receipts` directory following the naming convention
+   `ncl/receipts/<ncl-function-or-category-name>.rst`
+
+2. Add a new line to the `ncl/ncl_index/ncl-index-table.csv` file

Makefile

@@ -14,7 +14,12 @@ help:
 
 .PHONY: help Makefile
 
+clean-temp:
+	-rm -r -f tmp/
+
+
 # Catch-all target: route all unknown targets to Sphinx using the new
 # "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
 %: Makefile
 	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+	 @$(MAKE) clean-temp

README.md

@@ -1,3 +1,3 @@
-# geocat-applications
-
+# [GeoCAT Applications](https://ncar.github.io/geocat-applications/)
+[![Build and Deploy](https://github.com/NCAR/geocat-applications/actions/workflows/deploy.yml/badge.svg)](https://github.com/NCAR/geocat-applications/actions/workflows/deploy.yml)
 This is the source repository for GeoCAT-applications.

applications/applications.rst

@@ -0,0 +1,46 @@
+.. _applications:
+
+.. grid:: 4
+    :gutter: 2
+
+    .. grid-item::
+
+        .. grid:: 1
+            :gutter: 1
+
+            .. card:: `Plot Types <applications/plot_types/plot_types.rst>`_
+
+                - `Contour <applications/plot_types/contour.ipynb>`_
+                - Plot type 2
+                - Plot type 3
+
+
+    .. grid-item::
+
+        .. grid:: 1
+            :gutter: 1
+
+            .. card:: `Data Analysis <applications/data_analysis/data_analysis.rst>`_
+
+                - `Data Analysis 1 <applications/data_analysis/sample.ipynb>`_
+
+    .. grid-item::
+
+        .. grid:: 1
+            :gutter: 1
+
+            .. card:: `File I/O <applications/file_io/file_io.rst>`_
+
+                - `File I/O 1 <applications/file_io/sample.ipynb>`_
+
+            .. card:: Date Time Routines
+
+
+    .. grid-item::
+
+        .. grid:: 1
+            :gutter: 1
+
+            .. card:: Regridding
+
+            .. card:: Interpolation

applications/ncl_applications.rst

@@ -0,0 +1,4 @@
+.. _ncl_applications:
+
+NCL Applications
+================

conf.py

@@ -13,12 +13,26 @@
 # -- Project information -----------------------------------------------------
 
 import sys
+import os
 from sphinx.util import logging
+import pandas as pd
 
-print("sys.path:", sys.path)
+LOGGER = logging.getLogger("conf")
 
+LOGGER.info("sys.path: " + str(sys.path))
 
-LOGGER = logging.getLogger("conf")
+# create temp directory
+tmp_dir = 'tmp'  # must match the directory in Makefile and make.bat
+os.makedirs(tmp_dir, exist_ok=True)
+
+# sort ncl/ncl-index-table.csv
+df = pd.read_csv('ncl/ncl_index/ncl-index-table.csv')
+df['sort_column'] = df['NCL Function'].apply(lambda x: x[1] if len(x) > 1 else x)
+df = df.sort_values(by='sort_column')
+df = df.drop(columns=['sort_column'])
+df.to_csv(tmp_dir + '/ncl-index-table.csv', index=False)
+
+LOGGER.info("sorted ncl-index-table.csv")
 
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
@@ -158,7 +172,16 @@
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
 # This pattern also affects html_static_path and html_extra_path.
-exclude_patterns = ['README.md', '_build', '.DS_Store', 'ipynb_checkpoints']
+exclude_patterns = [
+    'README.md',
+    '_build',
+    '.DS_Store',
+    'ipynb_checkpoints',
+    '.github',
+    'ci',
+    'CONTRIBUTING.md',
+    'LICENSE.md',
+]
 
 # The reST default role (used for this markup: `text`) to use for all
 # documents.

index.rst

@@ -21,61 +21,23 @@
 ..    :scale: 100%
 ..   :align: right
 
-.. |
-.. |
+
 
 GeoCAT Applications
 ===================
 
-GeoCAT Applications is a community resource managed by the GeoCAT team. Inspired by the `NCL Applications <https://www.ncl.ucar.edu/Applications/>`_ page, this is designed to be a quick reference demonstrating capabilities within the Scientific Python Ecosystem that may be relevant to your geoscience workflows.
-
-.. grid:: 4
-    :gutter: 2
-
-    .. grid-item::
-
-        .. grid:: 1
-            :gutter: 1
-
-            .. card:: `Plot Types <applications/plot_types/plot_types.rst>`_
-
-                - `Contour <applications/plot_types/contour.ipynb>`_
-                - Plot type 2
-                - Plot type 3
-
-
-    .. grid-item::
-
-        .. grid:: 1
-            :gutter: 1
-
-            .. card:: `Data Analysis <applications/data_analysis/data_analysis>`_
-
-                - `Data Analysis 1 <applications/data_analysis/sample.ipynb>`_
-
-    .. grid-item::
-
-        .. grid:: 1
-            :gutter: 1
-
-            .. card:: `File I/O <applications/file_io/file_io>`_
-
-                - `File I/O 1 <applications/file_io/sample.ipynb>`_
-
-            .. card:: Date Time Routines
-
-
-    .. grid-item::
-
-        .. grid:: 1
-            :gutter: 1
-
-            .. card:: Regridding
+GeoCAT Applications is a community resource managed by the GeoCAT team. Inspired by the
+`NCL Applications <https://www.ncl.ucar.edu/Applications/>`_ page, this is designed to be a quick reference
+demonstrating capabilities within the Scientific Python Ecosystem that may be relevant to your geoscience workflows.
 
-            .. card:: Interpolation
+Python Examples
+---------------
 
+.. include:: applications/applications.rst
 
 
+.. TIP::
+    If you're looking for NCL to Python examples, please visit :ref:`ncl_applications`.
 
 
 .. toctree::
@@ -90,9 +52,10 @@ GeoCAT Applications is a community resource managed by the GeoCAT team. Inspired
 .. toctree::
     :maxdepth: 2
     :hidden:
-    :caption: NCL Index
+    :caption: NCL
 
-    NCL Index <ncl/ncl_index>
+    NCL Index <ncl/ncl_index/ncl_index>
+    NCL Applications <applications/ncl_applications.rst>
 
 .. toctree::
     :maxdepth: 2

make.bat

@@ -26,10 +26,13 @@ if errorlevel 9009 (
 )
 
 %SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
-goto end
+goto clean-temp
 
 :help
 %SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
 
+:clean-temp
+rd /s /q tmp
+
 :end
 popd

ncl/ncl_index/ncl-index-table.csv

@@ -0,0 +1,3 @@
+NCL Function,Description,Python Equivalent,Notes
+`example <https://www.ncl.ucar.edu/>`__,example,example,example
+a,a,a,a

ncl/ncl_index/ncl_index.rst

@@ -0,0 +1,14 @@
+.. _ncl_index:
+
+NCL Index
+=========
+
+.. Link to temp file with alphabetized version of csv file (see conf.py)
+.. csv-table::
+    :file: ../../tmp/ncl-index-table.csv
+    :width: 100%
+    :header-rows: 1
+
+
+.. note::
+    For more information on how we verify these recommendations, see the :ref:`receipts`.

ncl/receipts/receipts.rst

@@ -0,0 +1,18 @@
+.. This keeps the page from being included in the TOC, but allows it to be included in the build.
+
+:orphan:
+
+.. _receipts:
+
+Receipts List
+=============
+
+.. warning::
+    **This page is not meant to be useful to the typical user.** It is meant to be a reference for developers working on
+    the NCL Index or users interested in the "behind the curtain" details of how we verify entries to the NCL Index.
+
+.. This will automatically generates a list of all the files in the ncl/receipts directory.
+.. toctree::
+    :glob:
+
+    *

ncl/receipts/something-else.ipynb

@@ -0,0 +1,39 @@
+{
+ "cells": [
+  {
+   "metadata": {},
+   "cell_type": "markdown",
+   "source": "# Something else",
+   "id": "cc283431cbdce854"
+  },
+  {
+   "metadata": {},
+   "cell_type": "code",
+   "outputs": [],
+   "execution_count": null,
+   "source": "",
+   "id": "194f11e89c01919d"
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 2
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython2",
+   "version": "2.7.6"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}

ncl/receipts/something.ipynb

@@ -0,0 +1,39 @@
+{
+ "cells": [
+  {
+   "metadata": {},
+   "cell_type": "markdown",
+   "source": "# Hello",
+   "id": "cc553ef27145b766"
+  },
+  {
+   "metadata": {},
+   "cell_type": "code",
+   "outputs": [],
+   "execution_count": null,
+   "source": "",
+   "id": "c60e3d9f10a815a4"
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 2
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython2",
+   "version": "2.7.6"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}