From f518ee8432eb323f25cef12811173bc26c9ffa2d Mon Sep 17 00:00:00 2001 From: palewire Date: Mon, 6 Jun 2022 15:11:53 -0700 Subject: [PATCH] Dox --- .github/workflows/docs.yml | 29 +++++ Pipfile | 2 + Pipfile.lock | 187 +++++++++++++++++++++++++++- README.md | 72 +---------- docs/Makefile | 20 +++ docs/_static/css/custom.css | 234 ++++++++++++++++++++++++++++++++++++ docs/_templates/nav.html | 49 ++++++++ docs/conf.py | 43 +++++++ docs/index.md | 83 +++++++++++++ docs/make.bat | 35 ++++++ docs/requirements.txt | 2 + 11 files changed, 685 insertions(+), 71 deletions(-) create mode 100644 .github/workflows/docs.yml create mode 100644 docs/Makefile create mode 100644 docs/_static/css/custom.css create mode 100644 docs/_templates/nav.html create mode 100644 docs/conf.py create mode 100644 docs/index.md create mode 100644 docs/make.bat create mode 100644 docs/requirements.txt diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml new file mode 100644 index 00000000..1354bcf7 --- /dev/null +++ b/.github/workflows/docs.yml @@ -0,0 +1,29 @@ +name: "Build documentation" +on: + push: + pull_request: + workflow_dispatch: + +jobs: + docs: + name: "Build and deploy" + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v3 + + - uses: ammaraskar/sphinx-action@master + with: + docs-folder: "docs/" + + - uses: actions/upload-artifact@v1 + with: + name: documentation-html + path: docs/_build/html/ + + - uses: shallwefootball/s3-upload-action@master + with: + aws_key_id: ${{ secrets.PALEWIRE_DOCS_AWS_ACCESS_KEY_ID }} + aws_secret_access_key: ${{ secrets.PALEWIRE_DOCS_AWS_SECRET_ACCESS_KEY }} + aws_bucket: ${{ secrets.PALEWIRE_DOCS_AWS_BUCKET }} + source_dir: docs/_build/html/ + destination_dir: nws-wwa diff --git a/Pipfile b/Pipfile index bb0e920e..5933778a 100644 --- a/Pipfile +++ b/Pipfile @@ -11,6 +11,8 @@ pytest-vcr = "*" typing-extensions = "*" pre-commit = "*" setuptools-scm = "*" +sphinx = "*" +myst-parser = "*" [packages] fiona = "*" diff --git a/Pipfile.lock b/Pipfile.lock index 7bb291b5..08e25492 100644 --- a/Pipfile.lock +++ b/Pipfile.lock @@ -1,7 +1,7 @@ { "_meta": { "hash": { - "sha256": "78ae54ba8e387b27bb79e2b89ace5a06f6295d4b4fb0195e4be5c9a7098e7c59" + "sha256": "db6141fa626f9687701d0169e9bb1e140b4fadd7f0c8125e6ff6b0499b97a42e" }, "pipfile-spec": 6, "requires": { @@ -137,6 +137,13 @@ } }, "develop": { + "alabaster": { + "hashes": [ + "sha256:446438bdcca0e05bd45ea2de1668c1d9b032e1a9154c2c259092d77031ddd359", + "sha256:a661d72d58e6ea8a57f7a86e37d86716863ee5e92788398526d58b26a4e4dc02" + ], + "version": "==0.7.12" + }, "attrs": { "hashes": [ "sha256:2d27e3784d7a565d36ab851fe94887c5eccd6a463168875832a1be79c82828b4", @@ -145,6 +152,14 @@ "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3, 3.4'", "version": "==21.4.0" }, + "babel": { + "hashes": [ + "sha256:3f349e85ad3154559ac4930c3918247d319f21910d5ce4b25d439ed8693b98d2", + "sha256:98aeaca086133efb3e1e2aad0396987490c8425929ddbcfe0550184fdc54cd13" + ], + "markers": "python_version >= '3.6'", + "version": "==2.10.1" + }, "bleach": { "hashes": [ "sha256:08a1fe86d253b5c88c92cc3d810fd8048a16d15762e1e5b74d502256e5926aa1", @@ -276,11 +291,11 @@ }, "docutils": { "hashes": [ - "sha256:23010f129180089fbcd3bc08cfefccb3b890b0050e1ca00c867036e9d161b98c", - "sha256:679987caf361a7539d76e584cbeddc311e3aee937877c87346f31debc63e9d06" + "sha256:686577d2e4c32380bb50cbb22f575ed742d58168cee37e99117a854bcd88f125", + "sha256:cf316c8370a737a022b72b56874f6602acf974a37a9fba42ec2876387549fc61" ], "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3, 3.4'", - "version": "==0.18.1" + "version": "==0.17.1" }, "filelock": { "hashes": [ @@ -314,6 +329,14 @@ "markers": "python_version >= '3'", "version": "==3.3" }, + "imagesize": { + "hashes": [ + "sha256:1db2f82529e53c3e929e8926a1fa9235aa82d0bd0c580359c67ec31b2fddaa8c", + "sha256:cd1750d452385ca327479d45b64d9c7729ecf0b3969a58148298c77092261f9d" + ], + "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3'", + "version": "==1.3.0" + }, "importlib-metadata": { "hashes": [ "sha256:5d26852efe48c0a32b0509ffbc583fda1a2266545a78d104a6f4aff3db17d700", @@ -337,6 +360,14 @@ "markers": "sys_platform == 'linux'", "version": "==0.8.0" }, + "jinja2": { + "hashes": [ + "sha256:31351a702a408a9e7595a8fc6150fc3f43bb6bf7e319770cbc0db9df9437e852", + "sha256:6088930bfe239f0e6710546ab9c19c9ef35e29792895fed6e6e31a023a182a61" + ], + "markers": "python_version >= '3.7'", + "version": "==3.1.2" + }, "keyring": { "hashes": [ "sha256:9ef58314bcc823f426b49ec787539a2d73571b37de4cd498f839803b01acff1e", @@ -345,6 +376,60 @@ "markers": "python_version >= '3.7'", "version": "==23.5.1" }, + "markdown-it-py": { + "hashes": [ + "sha256:93de681e5c021a432c63147656fe21790bc01231e0cd2da73626f1aa3ac0fe27", + "sha256:cf7e59fed14b5ae17c0006eff14a2d9a00ed5f3a846148153899a0224e2c07da" + ], + "markers": "python_version >= '3.7'", + "version": "==2.1.0" + }, + "markupsafe": { + "hashes": [ + "sha256:0212a68688482dc52b2d45013df70d169f542b7394fc744c02a57374a4207003", + "sha256:089cf3dbf0cd6c100f02945abeb18484bd1ee57a079aefd52cffd17fba910b88", + "sha256:10c1bfff05d95783da83491be968e8fe789263689c02724e0c691933c52994f5", + "sha256:33b74d289bd2f5e527beadcaa3f401e0df0a89927c1559c8566c066fa4248ab7", + "sha256:3799351e2336dc91ea70b034983ee71cf2f9533cdff7c14c90ea126bfd95d65a", + "sha256:3ce11ee3f23f79dbd06fb3d63e2f6af7b12db1d46932fe7bd8afa259a5996603", + "sha256:421be9fbf0ffe9ffd7a378aafebbf6f4602d564d34be190fc19a193232fd12b1", + "sha256:43093fb83d8343aac0b1baa75516da6092f58f41200907ef92448ecab8825135", + "sha256:46d00d6cfecdde84d40e572d63735ef81423ad31184100411e6e3388d405e247", + "sha256:4a33dea2b688b3190ee12bd7cfa29d39c9ed176bda40bfa11099a3ce5d3a7ac6", + "sha256:4b9fe39a2ccc108a4accc2676e77da025ce383c108593d65cc909add5c3bd601", + "sha256:56442863ed2b06d19c37f94d999035e15ee982988920e12a5b4ba29b62ad1f77", + "sha256:671cd1187ed5e62818414afe79ed29da836dde67166a9fac6d435873c44fdd02", + "sha256:694deca8d702d5db21ec83983ce0bb4b26a578e71fbdbd4fdcd387daa90e4d5e", + "sha256:6a074d34ee7a5ce3effbc526b7083ec9731bb3cbf921bbe1d3005d4d2bdb3a63", + "sha256:6d0072fea50feec76a4c418096652f2c3238eaa014b2f94aeb1d56a66b41403f", + "sha256:6fbf47b5d3728c6aea2abb0589b5d30459e369baa772e0f37a0320185e87c980", + "sha256:7f91197cc9e48f989d12e4e6fbc46495c446636dfc81b9ccf50bb0ec74b91d4b", + "sha256:86b1f75c4e7c2ac2ccdaec2b9022845dbb81880ca318bb7a0a01fbf7813e3812", + "sha256:8dc1c72a69aa7e082593c4a203dcf94ddb74bb5c8a731e4e1eb68d031e8498ff", + "sha256:8e3dcf21f367459434c18e71b2a9532d96547aef8a871872a5bd69a715c15f96", + "sha256:8e576a51ad59e4bfaac456023a78f6b5e6e7651dcd383bcc3e18d06f9b55d6d1", + "sha256:96e37a3dc86e80bf81758c152fe66dbf60ed5eca3d26305edf01892257049925", + "sha256:97a68e6ada378df82bc9f16b800ab77cbf4b2fada0081794318520138c088e4a", + "sha256:99a2a507ed3ac881b975a2976d59f38c19386d128e7a9a18b7df6fff1fd4c1d6", + "sha256:a49907dd8420c5685cfa064a1335b6754b74541bbb3706c259c02ed65b644b3e", + "sha256:b09bf97215625a311f669476f44b8b318b075847b49316d3e28c08e41a7a573f", + "sha256:b7bd98b796e2b6553da7225aeb61f447f80a1ca64f41d83612e6139ca5213aa4", + "sha256:b87db4360013327109564f0e591bd2a3b318547bcef31b468a92ee504d07ae4f", + "sha256:bcb3ed405ed3222f9904899563d6fc492ff75cce56cba05e32eff40e6acbeaa3", + "sha256:d4306c36ca495956b6d568d276ac11fdd9c30a36f1b6eb928070dc5360b22e1c", + "sha256:d5ee4f386140395a2c818d149221149c54849dfcfcb9f1debfe07a8b8bd63f9a", + "sha256:dda30ba7e87fbbb7eab1ec9f58678558fd9a6b8b853530e176eabd064da81417", + "sha256:e04e26803c9c3851c931eac40c695602c6295b8d432cbe78609649ad9bd2da8a", + "sha256:e1c0b87e09fa55a220f058d1d49d3fb8df88fbfab58558f1198e08c1e1de842a", + "sha256:e72591e9ecd94d7feb70c1cbd7be7b3ebea3f548870aa91e2732960fa4d57a37", + "sha256:e8c843bbcda3a2f1e3c2ab25913c80a3c5376cd00c6e8c4a86a89a28c8dc5452", + "sha256:efc1913fd2ca4f334418481c7e595c00aad186563bbc1ec76067848c7ca0a933", + "sha256:f121a1420d4e173a5d96e47e9a0c0dcff965afdf1626d28de1460815f7c4ee7a", + "sha256:fc7b548b17d238737688817ab67deebb30e8073c95749d55538ed473130ec0c7" + ], + "markers": "python_version >= '3.7'", + "version": "==2.1.1" + }, "mccabe": { "hashes": [ "sha256:ab8a6258860da4b6677da4bd2fe5dc2c659cff31b3ee4f7f5d64e79735b80d42", @@ -352,6 +437,22 @@ ], "version": "==0.6.1" }, + "mdit-py-plugins": { + "hashes": [ + "sha256:b1279701cee2dbf50e188d3da5f51fee8d78d038cdf99be57c6b9d1aa93b4073", + "sha256:ecc24f51eeec6ab7eecc2f9724e8272c2fb191c2e93cf98109120c2cace69750" + ], + "markers": "python_version ~= '3.6'", + "version": "==0.3.0" + }, + "mdurl": { + "hashes": [ + "sha256:6a8f6804087b7128040b2fb2ebe242bdc2affaeaa034d5fc9feeed30b443651b", + "sha256:f79c9709944df218a4cdb0fcc0b0c7ead2f44594e3e84dc566606f04ad749c20" + ], + "markers": "python_version >= '3.7'", + "version": "==0.1.1" + }, "multidict": { "hashes": [ "sha256:0327292e745a880459ef71be14e709aaea2f783f3537588fb4ed09b6c01bca60", @@ -417,6 +518,14 @@ "markers": "python_version >= '3.7'", "version": "==6.0.2" }, + "myst-parser": { + "hashes": [ + "sha256:1635ce3c18965a528d6de980f989ff64d6a1effb482e1f611b1bfb79e38f3d98", + "sha256:4c076d649e066f9f5c7c661bae2658be1ca06e76b002bb97f02a09398707686c" + ], + "index": "pypi", + "version": "==0.17.2" + }, "nodeenv": { "hashes": [ "sha256:3ef13ff90291ba2a4a7a4ff9a979b63ffdd00a464dbe04acf0ea6471517a4c2b", @@ -527,6 +636,13 @@ "index": "pypi", "version": "==1.0.2" }, + "pytz": { + "hashes": [ + "sha256:1e760e2fe6a8163bc0b3d9a19c4f84342afa0a2affebfaa84b01b978a02ecaa7", + "sha256:e68985985296d9a66a881eb3193b0906246245294a881e7c8afe623866ac6a5c" + ], + "version": "==2022.1" + }, "pyyaml": { "hashes": [ "sha256:0283c35a6a9fbf047493e3a0ce8d79ef5030852c51e9d911a27badfde0605293", @@ -637,6 +753,69 @@ "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3'", "version": "==1.16.0" }, + "snowballstemmer": { + "hashes": [ + "sha256:09b16deb8547d3412ad7b590689584cd0fe25ec8db3be37788be3810cbf19cb1", + "sha256:c8e1716e83cc398ae16824e5572ae04e0d9fc2c6b985fb0f900f5f0c96ecba1a" + ], + "version": "==2.2.0" + }, + "sphinx": { + "hashes": [ + "sha256:7bf8ca9637a4ee15af412d1a1d9689fec70523a68ca9bb9127c2f3eeb344e2e6", + "sha256:ebf612653238bcc8f4359627a9b7ce44ede6fdd75d9d30f68255c7383d3a6226" + ], + "index": "pypi", + "version": "==4.5.0" + }, + "sphinxcontrib-applehelp": { + "hashes": [ + "sha256:806111e5e962be97c29ec4c1e7fe277bfd19e9652fb1a4392105b43e01af885a", + "sha256:a072735ec80e7675e3f432fcae8610ecf509c5f1869d17e2eecff44389cdbc58" + ], + "markers": "python_version >= '3.5'", + "version": "==1.0.2" + }, + "sphinxcontrib-devhelp": { + "hashes": [ + "sha256:8165223f9a335cc1af7ffe1ed31d2871f325254c0423bc0c4c7cd1c1e4734a2e", + "sha256:ff7f1afa7b9642e7060379360a67e9c41e8f3121f2ce9164266f61b9f4b338e4" + ], + "markers": "python_version >= '3.5'", + "version": "==1.0.2" + }, + "sphinxcontrib-htmlhelp": { + "hashes": [ + "sha256:d412243dfb797ae3ec2b59eca0e52dac12e75a241bf0e4eb861e450d06c6ed07", + "sha256:f5f8bb2d0d629f398bf47d0d69c07bc13b65f75a81ad9e2f71a63d4b7a2f6db2" + ], + "markers": "python_version >= '3.6'", + "version": "==2.0.0" + }, + "sphinxcontrib-jsmath": { + "hashes": [ + "sha256:2ec2eaebfb78f3f2078e73666b1415417a116cc848b72e5172e596c871103178", + "sha256:a9925e4a4587247ed2191a22df5f6970656cb8ca2bd6284309578f2153e0c4b8" + ], + "markers": "python_version >= '3.5'", + "version": "==1.0.1" + }, + "sphinxcontrib-qthelp": { + "hashes": [ + "sha256:4c33767ee058b70dba89a6fc5c1892c0d57a54be67ddd3e7875a18d14cba5a72", + "sha256:bd9fc24bcb748a8d51fd4ecaade681350aa63009a347a8c14e637895444dfab6" + ], + "markers": "python_version >= '3.5'", + "version": "==1.0.3" + }, + "sphinxcontrib-serializinghtml": { + "hashes": [ + "sha256:352a9a00ae864471d3a7ead8d7d79f5fc0b57e8b3f95e9867eb9eb28999b92fd", + "sha256:aa5f6de5dfdf809ef505c4895e51ef5c9eac17d0f287933eb49ec495280b6952" + ], + "markers": "python_version >= '3.5'", + "version": "==1.1.5" + }, "toml": { "hashes": [ "sha256:806143ae5bfb6a3c6e736a764057db0e6a0e05e338b5630894a5f779cabb4f9b", diff --git a/README.md b/README.md index 251c9f9c..e70de436 100644 --- a/README.md +++ b/README.md @@ -1,68 +1,6 @@ -Download watch, warning and advisory data from the National Weather Service +### Links -Hourly scrapes powered by a GitHub Action are stored in the `data` directory. - -## Installation - -```bash -pipenv install nws-wwa -``` - -## Command-line usage - -```bash -Usage: nwswwa [OPTIONS] COMMAND [ARGS]... - -A command-line interface for downloading watch, warning and advisory data -from the National Weather Service. Returns GeoJSON. - -Options: ---help Show this message and exit. - -Commands: -all All watch, warning and advisory data -hazards All hazard data -warnings All warnings data -``` - -Download data from the National Weather Service. - -```bash -nwswwa all -nwswwa hazards -nwswwa warnings -``` - -## Python usage - -Import the library. - -```python -import nws_wwa - -data = nws_wwa.get_all() -data = nws_wwa.get_hazards() -data = nws_wwa.get_warnings() -``` - -## Contributing - -Install dependencies for development. - -```bash -pipenv install --dev -``` - -Run tests. - -```bash -pipenv run python setup.py test -``` - -## Developing the CLI - -The command-line interface is implemented using Click and setuptools. To install it locally for development inside your virtual environment, run the following installation command, as prescribed by the [Click documentation](https://click.palletsprojects.com/en/7.x/setuptools/#setuptools-integration). - -```bash -pipenv run pip install --editable . -``` +* Docs: [palewi.re/docs/nws-wwa/](https://palewi.re/docs/nws-wwa/) +* Issues: [github.com/datadesk/nws-wwa/issues](https://github.com/datadesk/nws-wwa/issues) +* Packaging: [pypi.python.org/pypi/nws-wwa](https://pypi.python.org/pypi/nws-wwa) +* Testing: [github.com/datadesk/nws-wwa/actions](https://github.com/datadesk/nws-wwa/actions) diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 00000000..d4bb2cbb --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,20 @@ +# Minimal makefile for Sphinx documentation +# + +# You can set these variables from the command line, and also +# from the environment for the first two. +SPHINXOPTS ?= +SPHINXBUILD ?= sphinx-build +SOURCEDIR = . +BUILDDIR = _build + +# Put it first so that "make" without argument is like "make help". +help: + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +.PHONY: help Makefile + +# 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) diff --git a/docs/_static/css/custom.css b/docs/_static/css/custom.css new file mode 100644 index 00000000..b6b8bd06 --- /dev/null +++ b/docs/_static/css/custom.css @@ -0,0 +1,234 @@ +@import url('https://fonts.googleapis.com/css2?family=Libre+Franklin:ital,wght@0,400;0,700;0,800;1,400;1,800&display=swap'); + +div.document { + margin-top: 0; +} + +div.body { + min-width: 0 !important; +} + +div.body p, div.body li { + line-height: 1.45; +} + +div.body li { + margin-bottom: 4px; +} + +div.topic { + margin: 0; + padding: 8px 12px; +} + +p.topic-title { + margin: 0; +} + +div.topic ul { + margin-top: 6px; +} +@media screen and (max-width: 870px) { + ul { + margin: 10px 0 10px 20px; + } +} + +div.sphinxsidebar h1.logo, +div.sphinxsidebar h3 { + font-family: 'Libre Franklin', "Helvetica", "Liberation Sans", Arial, sans-serif; +} + +div.sphinxsidebarwrapper h1.logo { + font-size: 1.85em; + font-weight: 800; +} + +@media (min-width: 875px) { + div.sphinxsidebar { + margin-top: 85px; + } +} + +@media screen and (max-width: 875px) { + div.sphinxsidebar { + width: auto; + padding: 10px 20px; + margin: 50px 0 0 0; + } +} + +div.admonition { + padding: 15px; +} + +div.warning { + background-color: #EEE; + border: 1px solid #CCC; +} + +div.admonition p.admonition-title { + font-family: 'Libre Franklin', "Helvetica", "Liberation Sans", Arial, sans-serif; + margin: 0; +} + +div.related nav { + padding-right: 10px; +} + +body { + font-family: 'Libre Franklin', "Helvetica", "Liberation Sans", Arial, sans-serif; + font-size: 20px; + line-height: 1.45; + text-align: left; +} +@media screen and (max-width: 875px) { + body { + margin: 0; + padding: 0; + } + div.body > .section, + div.body > section { + padding: 0 20px; + } +} + +@media (max-width: 550px) { + body { + font-size: 0.85em; + } +} + +div.body h1, div.body h2, div.body h3, div.body h4, div.body h5, div.body h6 { + font-family: 'Libre Franklin', "Helvetica", "Liberation Sans", Arial, sans-serif; + font-weight: 700; +} + +div.body h1 { + font-weight: 800; + font-size: 220%; +} + +pre { + padding: 7px; +} + +.cell_output { + overflow: auto; +} + +.toctree-wrapper p.caption { + font-weight: 700; +} + +.toggle-details { + display: none; +} + +.row { + width: 100%; + max-width: 660px; + margin: 0 auto; + overflow: hidden; +} +.row .fivecol { + width: 43%; + float: right; + min-height: 1px; +} +.row .sevencol { + width: 37%; + float: left; + min-height: 1px; +} +@media (max-width: 550px) { + .row .fivecol, .row .sevencol { + padding: 0 20px; + } +} + +/* The header */ +nav { + display: block; + margin-top: 0.75em; + margin-bottom: 0.5em; + font-size: 1em; + line-height: 1.7em; +} +nav .shingle { + font-size: 1.7em; + font-weight: bold; + text-align: left; + padding-left: 0.15em; +} +nav .shingle a { + text-decoration: none; + font-weight: bold; + color: #000; +} +nav .shingle a:hover { + color: #686868; +} +@media (max-width: 550px) { + nav .shingle { + float: left; + margin-bottom: 5px; + padding-left: 0; + } +} +nav .links { + text-align: right; +} +nav .links ul { + float: right; + list-style-type: none; + margin: 4px 0 0 0; +} +nav .links li { + float: left; + list-style-position: inside; + margin-left: 0.5em; + font-size: 0.9em; + font-weight: 300; + margin-bottom: 0; +} +@media (max-width: 550px) { + nav .links li { + font-size: .825em; + } +} +nav .links li a { + text-decoration: none; +} +nav .links li a:hover { + text-decoration: underline; +} +.last { + margin-right: 0; +} + +.topbar { + border-bottom: solid 10px #e5e5e5; + margin-bottom: 20px; + width: 100%; +} + +a:link { + text-decoration: none; + color: #686868; +} +a:visited { + text-decoration: none; + color: #686868; +} +a:hover { + text-decoration: underline; +} +a:active { + text-decoration: underline; + color: #000; +} + +.contents ul p { + margin-bottom: 0; +} diff --git a/docs/_templates/nav.html b/docs/_templates/nav.html new file mode 100644 index 00000000..cd40a0ec --- /dev/null +++ b/docs/_templates/nav.html @@ -0,0 +1,49 @@ + + + +
+
+
diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 00000000..9d6e7d5b --- /dev/null +++ b/docs/conf.py @@ -0,0 +1,43 @@ +"""Configure Sphinx configuration.""" +import os +import sys +from datetime import datetime + +# Insert the parent directory into the path +sys.path.insert(0, os.path.abspath("..")) + +extensions = [ + "myst_parser", +] +templates_path = ["_templates"] +source_suffix = ".rst" +master_doc = "index" + +project = "nws-wwa" +year = datetime.now().year +copyright = f"{year} Ben Welsh" + +exclude_patterns = ["_build"] + +html_theme = "alabaster" +html_sidebars = { + "**": [ + # "about.html", + # "navigation.html", + "relations.html", + "searchbox.html", + "donate.html", + ] +} +html_theme_options = { + "canonical_url": f"https://palewi.re/docs/{project}/", + "show_powered_by": False, + "show_relbar_bottom": True, +} + +html_static_path = ["_static"] +html_css_files = [ + "css/custom.css", +] + +pygments_style = "sphinx" diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 00000000..9fb97d05 --- /dev/null +++ b/docs/index.md @@ -0,0 +1,83 @@ +```{include} _templates/nav.html +``` + +# nws-wwa + +Download watch, warning and advisory data from the National Weather Service + +```{contents} Table of contents +:local: +:depth: 2 +``` + +## Installation + +```bash +pipenv install nws-wwa +``` + +## Command-line usage + +```bash +Usage: nwswwa [OPTIONS] COMMAND [ARGS]... + +A command-line interface for downloading watch, warning and advisory data +from the National Weather Service. Returns GeoJSON. + +Options: +--help Show this message and exit. + +Commands: +all All watch, warning and advisory data +hazards All hazard data +warnings All warnings data +``` + +Download data from the National Weather Service. + +```bash +nwswwa all +nwswwa hazards +nwswwa warnings +``` + +## Python usage + +Import the library. + +```python +import nws_wwa + +data = nws_wwa.get_all() +data = nws_wwa.get_hazards() +data = nws_wwa.get_warnings() +``` + +## Contributing + +Install dependencies for development. + +```bash +pipenv install --dev +``` + +Run tests. + +```bash +pipenv run python setup.py test +``` + +## Developing the CLI + +The command-line interface is implemented using Click and setuptools. To install it locally for development inside your virtual environment, run the following installation command, as prescribed by the [Click documentation](https://click.palletsprojects.com/en/7.x/setuptools/#setuptools-integration). + +```bash +pipenv run pip install --editable . +``` + +## Links + +* Docs: [palewi.re/docs/nws-wwa/](https://palewi.re/docs/nws-wwa/) +* Issues: [github.com/datadesk/nws-wwa/issues](https://github.com/datadesk/nws-wwa/issues) +* Packaging: [pypi.python.org/pypi/nws-wwa](https://pypi.python.org/pypi/nws-wwa) +* Testing: [github.com/datadesk/nws-wwa/actions](https://github.com/datadesk/nws-wwa/actions) diff --git a/docs/make.bat b/docs/make.bat new file mode 100644 index 00000000..32bb2452 --- /dev/null +++ b/docs/make.bat @@ -0,0 +1,35 @@ +@ECHO OFF + +pushd %~dp0 + +REM Command file for Sphinx documentation + +if "%SPHINXBUILD%" == "" ( + set SPHINXBUILD=sphinx-build +) +set SOURCEDIR=. +set BUILDDIR=_build + +%SPHINXBUILD% >NUL 2>NUL +if errorlevel 9009 ( + echo. + echo.The 'sphinx-build' command was not found. Make sure you have Sphinx + echo.installed, then set the SPHINXBUILD environment variable to point + echo.to the full path of the 'sphinx-build' executable. Alternatively you + echo.may add the Sphinx directory to PATH. + echo. + echo.If you don't have Sphinx installed, grab it from + echo.https://www.sphinx-doc.org/ + exit /b 1 +) + +if "%1" == "" goto help + +%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% +goto end + +:help +%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% + +:end +popd diff --git a/docs/requirements.txt b/docs/requirements.txt new file mode 100644 index 00000000..98a3c62a --- /dev/null +++ b/docs/requirements.txt @@ -0,0 +1,2 @@ +sphinx +myst-parser