Documentation using mkdocs

.github/workflows/ci.yml

@@ -0,0 +1,23 @@
+name: ci
+on:
+  push:
+    branches:
+      - master
+      - main
+      - documentation-mkdocs
+permissions:
+  contents: write
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - uses: actions/setup-python@v4
+        with:
+          python-version: 3.x
+      - uses: actions/cache@v2
+        with:
+          key: ${{ github.ref }}
+          path: .cache
+      - run: pip install mkdocs-material
+      - run: mkdocs gh-deploy --remote-branch gh-pages --force

.gitignore

@@ -1,3 +1,6 @@
 node_modules
 npm-debug.log
 .DS_Store
+
+.idea/
+.venv/

README.md

@@ -31,36 +31,36 @@ Here is where you can find all documentation for the [Pelias geocoder](https://g
 ### Core Features and API Documentation
 
 #### Endpoint descriptions
-- [Forward geocoding](search.md) (**/v1/search**) to find a place by searching for an address or name
-- [Reverse geocoding](reverse.md) (**/v1/reverse**) to find what is located at a certain coordinate location
-- [Autocomplete](autocomplete.md) (**/v1/autocomplete**) to give real-time result suggestions without having to type the whole location
-- [Structured Geocoding](structured-geocoding.md) (**/v1/search/structured**) (*beta*) to find a place with data already separated into housenumber, street, city, etc
-- [Place endpoint](place.md) (**/v1/place**) for details on a place returned from a previous query
+- [Forward geocoding](site/documentation/search.md) (**/v1/search**) to find a place by searching for an address or name
+- [Reverse geocoding](site/documentation/reverse.md) (**/v1/reverse**) to find what is located at a certain coordinate location
+- [Autocomplete](site/documentation/autocomplete.md) (**/v1/autocomplete**) to give real-time result suggestions without having to type the whole location
+- [Structured Geocoding](site/documentation/structured-geocoding.md) (**/v1/search/structured**) (*beta*) to find a place with data already separated into housenumber, street, city, etc
+- [Place endpoint](site/documentation/place.md) (**/v1/place**) for details on a place returned from a previous query
 
-_Not sure which Endpoint to use? We have a [page](search-workflows.md) for that_
+_Not sure which Endpoint to use? We have a [page](site/documentation/search-workflows.md) for that_
 
 #### Query parameters and options
-- [Global coverage with prioritized local results](search.md#prioritize-results-by-proximity)
-- [Language support](language-codes.md) for seeing results in different languages
+- [Global coverage with prioritized local results](site/documentation/search.md#prioritize-results-by-proximity)
+- [Language support](site/documentation/language-codes.md) for seeing results in different languages
 
 #### Response Properties
 
-- [Full list of response properties](response.md)
-- [Confidence scores, match\_types and other tools for determining result quality](result_quality.md)
+- [Full list of response properties](site/documentation/response.md)
+- [Confidence scores, match\_types and other tools for determining result quality](site/documentation/result-quality.md)
 
 ### Data Sources
-- [Pelias data sources](data-sources.md)
+- [Pelias data sources](site/documentation/data-sources.md)
 
 ### Running your own Pelias
-- [Getting started](getting_started_install.md) Start here if you're looking to install Pelias
-- [Pelias from scratch](pelias_from_scratch.md) More in-depth instructions for installing Pelias
-- [Full planet build considerations](full_planet_considerations.md) Special information on running a full planet Pelias build
-- [Service descriptions](services.md) A description of all the Pelias services, and when they are used
-- [Software Requirements](requirements.md) A list of all software requirements for Pelias
+- [Getting started](site/documentation/getting-started-install.md) Start here if you're looking to install Pelias
+- [Pelias from scratch](site/documentation/pelias-from-scratch.md) More in-depth instructions for installing Pelias
+- [Full planet build considerations](site/documentation/full-planet-considerations.md) Special information on running a full planet Pelias build
+- [Service descriptions](site/documentation/services.md) A description of all the Pelias services, and when they are used
+- [Software Requirements](site/documentation/requirements.md) A list of all software requirements for Pelias
 
 ### Pelias project development
-- [Release notes](release-notes.md). See notable changes in Pelias over time
-- [Development roadmap](development/roadmap.md). Plans for future improvements to Pelias. Read this to see what's coming and how you can help
+- [Release notes](site/release-notes.md). See notable changes in Pelias over time
+- [Development roadmap](site/development/roadmap.md). Plans for future improvements to Pelias. Read this to see what's coming and how you can help
 
 ### Misc
-- [Glossary of common terms](glossary.md)
+- [Glossary of common terms](site/documentation/glossary.md)

mkdocs.yml

@@ -0,0 +1,99 @@
+site_name: Pelias Geocoder
+docs_dir: site
+site_dir: generated
+theme:
+  name: material
+  font:
+    text: Inter
+    code: JetBrains Mono
+  logo: assets/Pelias-Logo_horizontal_secondary.png
+  favicon: assets/favicon_64x64.png
+  features:
+    - navigation.instant
+    - navigation.tracking
+    - navigation.tabs
+    - navigation.tabs.sticky
+    - navigation.sections
+    - navigation.top
+    - toc.follow
+    - search.suggest
+    - search.highlight
+    - content.tabs.link
+    - content.code.annotation
+    - content.code.copy
+    - navigation.footer
+  palette:
+
+    # Palette toggle for light mode
+    - media: "(prefers-color-scheme: light)"
+      scheme: default
+      toggle:
+        icon: material/weather-sunny
+        name: Switch to dark mode
+
+    # Palette toggle for dark mode
+    - media: "(prefers-color-scheme: dark)"
+      scheme: slate
+      toggle:
+        icon: material/weather-night
+        name: Switch to light mode
+
+extra_css:
+  - stylesheets/extra.css
+
+extra:
+  social:
+    - icon: fontawesome/brands/github
+      link: https://github.com/pelias/
+    - icon: fontawesome/brands/twitter
+      link: https://twitter.com/pelias_geocoder
+    - icon: fontawesome/brands/gitter
+      link: https://gitter.im/pelias/pelias
+
+markdown_extensions:
+  - pymdownx.highlight:
+      anchor_linenums: true
+  - pymdownx.inlinehilite
+  - pymdownx.snippets
+  - admonition
+  - footnotes
+  - pymdownx.details
+  - pymdownx.superfences
+  - pymdownx.mark
+  - attr_list
+
+nav:
+  - Pelias:
+    - "index.md"
+    - "fun-facts.md"
+  - Documentation:
+      - 'documentation/index.md'
+      - Getting Started: 'documentation/getting-started-install.md'
+      - Add Search to a Map: 'documentation/add-search-to-a-map.md'
+      - Forward Geocoding: 'documentation/search.md'
+      - Reverse Geocoding: 'documentation/reverse.md'
+      - Autocomplete: 'documentation/autocomplete.md'
+      - Structured Geocoding: 'documentation/structured-geocoding.md'
+      - Place Endpoint: 'documentation/place.md'
+      - Search Workflows: 'documentation/search-workflows.md'
+      - Search Response: 'documentation/response.md'
+      - Result Quality: 'documentation/result-quality.md'
+      - Searching Address: 'documentation/addresses.md'
+      - Data Sources: 'documentation/data-sources.md'
+      - Pelias from Scratch: 'documentation/pelias-from-scratch.md'
+      - Full Planet Build: 'documentation/full-planet-considerations.md'
+      - Language Support: 'documentation/language-codes.md'
+      - Requirements: 'documentation/requirements.md'
+      - Pelias Services: 'documentation/services.md'
+      - CORS: 'documentation/use-cors.md'
+      - HTTP status codes: 'documentation/http-status-codes.md'
+      - Glossary: 'documentation/glossary.md'
+  - Development:
+      - Repository List: 'development/repository-list.md'
+      - Roadmap: 'development/roadmap.md'
+      - Code of Conduct: 'development/code-of-conduct.md'
+  - Contribute: 'contributing.md'
+  - Release Notes: 'release-notes.md'
+  - Get an API Key: 'https://geocode.earth/'
+
+copyright: Pelias is a free open source project.

requirements.txt

@@ -0,0 +1,64 @@
+attrs==22.1.0
+build==0.10.0
+CacheControl==0.12.11
+certifi==2022.9.24
+cffi==1.15.1
+charset-normalizer==2.1.1
+cleo==2.0.1
+click==8.1.3
+colorama==0.4.6
+crashtest==0.4.1
+cryptography==37.0.4
+distlib==0.3.6
+dulwich==0.21.3
+filelock==3.8.0
+ghp-import==2.1.0
+html5lib==1.1
+idna==3.4
+installer==0.7.0
+jaraco.classes==3.2.3
+jeepney==0.8.0
+Jinja2==3.1.2
+jsonschema==4.16.0
+keyring==23.9.3
+lockfile==0.12.2
+Markdown==3.3.7
+MarkupSafe==2.1.2
+mergedeep==1.3.4
+mkdocs==1.4.2
+mkdocs-material==9.1.6
+mkdocs-material-extensions==1.1.1
+more-itertools==8.14.0
+msgpack==1.0.4
+packaging==22.0
+pexpect==4.8.0
+pipenv==2023.3.20
+pkginfo==1.9.6
+platformdirs==2.5.2
+poetry==1.4.2
+poetry-core==1.5.2
+poetry-plugin-export==1.3.0
+ptyprocess==0.7.0
+pycparser==2.21
+Pygments==2.15.0
+pymdown-extensions==9.11
+pyproject_hooks==1.0.0
+pyrsistent==0.18.1
+python-dateutil==2.8.2
+PyYAML==6.0
+pyyaml_env_tag==0.1
+rapidfuzz==2.13.7
+regex==2023.3.23
+requests==2.28.1
+requests-toolbelt==0.9.1
+SecretStorage==3.3.3
+shellingham==1.5.0
+six==1.16.0
+tomli==2.0.1
+tomlkit==0.11.5
+trove-classifiers==2022.12.22
+urllib3==1.26.12
+virtualenv==20.21.0
+virtualenv-clone==0.5.7
+watchdog==3.0.0
+webencodings==0.5.1

site/CNAME

@@ -0,0 +1 @@
+pelias-demo-unaffiliated.adhadse.com

site/contributing.md

@@ -0,0 +1,53 @@
+Pelias can't succeed without contributions from community members like you! Contributions come in many different shapes and sizes. In this file we provide guidance around two of the most common types of contributions: opening issues and opening pull requests.
+
+# Community Values 
+
+We ask that you are respectful when contributing to Pelias or engaging with our community. As a community, we appreciate the fact that contributors might be approaching the project from a different perspective and background. We hope that beginners as well as advanced users will be able to use and contribute back to Pelias. We want to encourage contributions and feedback from all over the world, which means that English might not be a contributor's native language, and sometimes we may encounter cultural differences. Contructive disagreements can be essential to moving a project forward, but disrespectful language or behavior will not be tolerated. 
+
+Above all, be patient, be respectful, and be kind!
+
+# Submitting Issues
+
+All issues for Pelias are housed in the [pelias/pelias](https://github.com/pelias/pelias) repo. Before opening an issue, be sure to search the repository to see if someone else has asked your question before. If not, go ahead and [open a new issue](https://github.com/pelias/pelias/issues/new).
+
+## Submitting technical bugs
+
+When submitting bug reports, please be sure to give us as much context as possible so that we can reproduce the error you encountered. Be sure to include:
+- System conditons (OS, browser, etc)
+- Steps to reproduce
+- Expected outcome
+- Actual outcome
+- Screenshots, if applicable
+- Code that exposes the bug, if you have it (such as a failing test or a barebones script)
+
+## Submitting issues around search result quality
+
+It's important to get feedback about the quality of local search results. When it comes to things like address structure, capitalization, and spelling errors, your local knowledge will make it easier for us to understand the problem. When submitting issues be sure to include:
+- Where in the world you were searching
+- Your search query
+- Your expected result
+- Your actual result
+
+
+# Pull Requests Welcome!
+
+## Project standards overview
+
+Pelias has several miscellaneous standards:
+
+- we use [JSHint](http://jshint.com/docs/) for linting
+- we use [Github Actions](https://github.com/) for continuous integration
+- we use [Winston](https://www.npmjs.com/package/winston) for logging
+- we *love* tests, especially when written with [tape](https://github.com/substack/tape)
+- we use [semver](http://semver.org/) for package versioning
+- we *loosely* use [JSDoc](http://usejsdoc.org/index.html) for documenting code, as described [here](in_code_documentation_guidelines.md)
+
+`jshint` and any unit tests in a project will be automatically invoked when you commit to an existing project; make
+sure they exit successfully!
+
+## Active contributors
+
+We'll gladly invite active contributors to become members of the [Pelias organization](https://github.com/pelias). New
+members will gain direct write permissions, *and with great power comes great responsibility*. To ensure that any new
+repositories that you create conform to Pelias standards, we developed [pelias-init](https://github.com/pelias/init), a
+simple project generator that will initialize all of the boilerplate needed to get started on something new.