diff --git a/.circleci/config.yml b/.circleci/config.yml
new file mode 100644
index 000000000..1e795c55d
--- /dev/null
+++ b/.circleci/config.yml
@@ -0,0 +1,27 @@
+version: 2.1
+jobs:
+ build_book:
+ docker:
+ - image: cimg/python:3.9
+ steps:
+ - checkout
+ - run:
+ name: setup environment
+ command: |
+ pip install --upgrade pip
+ pip install nox
+ pip list
+ - run:
+ name: Build book html
+ command: nox -s docs
+
+ - store_artifacts:
+ path: _build/html
+ destination: html
+
+# Tell CircleCI to use this workflow when it builds the site
+workflows:
+ version: 2
+ build_book:
+ jobs:
+ - build_book
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index f44c2597a..d792b9c2f 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -1,8 +1,23 @@
-# Contributing to this repository
+# Contributing Guide for the Python open source software packaging book
-Most of this repository is structured for **Sphinx**, a documentation engine built in Python.
+This is a community resource. We welcome contributions in the form of issues and/or pull requests to this guide.
-## Build the documentation
+* If you have an idea for something that should be included in the guide, [please open an issue here](https://github.com/pyOpenSci/python-package-guide/issues).
+* If you find a typo, feel free to [submit a pull request](https://github.com/pyOpenSci/python-package-guide/pulls) to modify the text directly. Or, if you are less comfortable with pull requests, feel free to open an issue.
+* If you want to see a larger change to the content of the guide book, please submit an issue first!
+
+## How this guide structured
+
+Most of this repository is structured for **Sphinx**, a documentation engine built in `Python`. We are using the Sphinx Book Theme and the `myST` syntax to create each page in this book.
+
+If you wish to contribute by working on the guide book locally, you
+will first need to
+
+1. Fork this repository
+2. Clone it locally
+3. Build the documentation locally
+
+## Instructions for building the documentation locally on your computer
The easiest way to build the documentation in this repository is to use `nox`,
a tool for quickly building environments and running commands within them.
diff --git a/README.md b/README.md
index 5b8dd393a..c41822d7b 100644
--- a/README.md
+++ b/README.md
@@ -1,4 +1,4 @@
-# pyOpenSci Packaging Guide
+# pyOpenSci Scientific Python Open Source Packaging Guide
diff --git a/_config.yml b/_config.yml
deleted file mode 100644
index 3524eee7b..000000000
--- a/_config.yml
+++ /dev/null
@@ -1,24 +0,0 @@
-# Book settings
-title: The pyOpenSci Developer Guide
-author: The pyOpenSci Community
-logo: images/logo/logo.png
-exclude_patterns: ["README.md"]
-
-repository:
- url: https://github.com/pyOpenSci/contributing-guide
- branch: main
-
-html:
- favicon: images/logo/logo.png
- google_analytics_id: UA-141260825-1
- use_edit_page_button: true
- use_issues_button: true
- use_repository_button: true
- home_page_in_navbar: false
- announcement: "
ATTENTION
-
- We are currently updating this book to stay tuned!
- The content should become more stable in early 2023.
-
-
- "
diff --git a/_static/pyos.css b/_static/pyos.css
new file mode 100644
index 000000000..f894a1d8b
--- /dev/null
+++ b/_static/pyos.css
@@ -0,0 +1,93 @@
+html, body {
+ font-size: 1.1rem;
+}
+
+body p {
+ /* font-family: $header-font; */
+ font-size: 1em;
+ font-family: 'Verdana', sans-serif!important;
+ color: #555!important;
+ line-height: 1.5em;
+}
+
+h1, h2, h3 {
+ font-family: 'Trebuchet MS', sans-serif;
+ color: #333!important;
+}
+
+h1 {
+ padding-bottom: 1em!important;
+}
+
+h3 {
+ padding-top: 1.4em;
+ margin-bottom: 14px;
+}
+
+/* hide the right sidebar */
+.col-md-3 .bd-toc .show .noprint {
+ display: none!important;
+}
+
+#main-content {
+ max-width: 80%;
+}
+
+.bd-toc {
+ color: #1abc9c;
+}
+
+@media (min-width: 720px){
+.col-md-3 {
+ flex: 0 0 25%;
+ /* max-width: 25%; */
+ display: none!important;
+ }
+}
+
+
+/* HEADER BLOCK 2 */
+div.header__block {
+color: #222;
+}
+
+.announcement div {
+background-color: #ccc;
+}
+
+.header-item.announcement, .header-item.announcement .noprint {
+ background-color:#ccc;
+}
+
+div .announcement .header-item .noprint, header-item.announcement {
+ background-color: #ccc!important;
+}
+
+/* notes */
+
+div.admonition.note .admonition-title, div.admonition.note .admonition-title::before {
+ background-color: #C1CFD4;
+ color: #222;
+
+}
+
+div.admonition.note {
+ border-color: #C1CFD4;
+ background-color: #E3F4FA;
+}
+
+
+div.admonition.important .admonition-title, div.admonition.important .admonition-title::before {
+background-color: #107762;
+color: #ffffff!important;
+}
+
+div.admonition.important .admonition-title {
+background-color: #107762;
+border-color: #1abc9c;
+}
+
+div.admonition.important {
+ border-color: #0e6654;
+ background-color: #ecfcf9;
+}
diff --git a/_templates/header.html b/_templates/header.html
new file mode 100644
index 000000000..778c419ea
--- /dev/null
+++ b/_templates/header.html
@@ -0,0 +1,7 @@
+
+
+
+
+
diff --git a/conf.py b/conf.py
index d32f54142..1839adea9 100644
--- a/conf.py
+++ b/conf.py
@@ -32,7 +32,6 @@
# ones.
extensions = [
"myst_nb",
- # "myst_parser",
"sphinx_design",
"sphinx_copybutton",
"sphinx.ext.intersphinx"
@@ -47,9 +46,10 @@
"repository_url": "https://github.com/pyopensci/python-package-guide",
"use_repository_button": True,
"google_analytics_id": "UA-141260825-1",
+ "show_toc_level": 1,
+ "toc_title": "On this page",
"external_links": [
- {"name": "link-one-name", "url": "https://www.pyopensci.org"},
- {"name": "link-two-name", "url": "https://pyopensci.org"}
+ {"pyOpenSci Website": "link-one-name", "url": "https://www.pyopensci.org"}
],
"announcement": "🚧 UNDER CONSTRUCTION: this guide is under heavy construction right now. 🚧"
}
@@ -79,6 +79,7 @@
#
html_theme = 'sphinx_book_theme'
html_static_path = ["_static"]
+html_css_files = ["pyos.css"]
html_title = "pyOpenSci Package Guide"
html_logo = "images/logo/logo.png"
diff --git a/documentation/contributing.md b/documentation/contributing.md
new file mode 100644
index 000000000..75c6a0fa3
--- /dev/null
+++ b/documentation/contributing.md
@@ -0,0 +1,45 @@
+# CONTRIBUTING file and License
+
+## CONTRIBUTING.md File for your Python Package
+
+Your python package should include a file called CONTRIBUTING.md located in the
+root of your repository (with your readme file).
+
+### Local development environment information
+
+The contributing file should include information to support a new contributing
+building your package locally. This includes:
+
+* instructions for setting up a development environment locally to work on your package
+* instructions for how the test suite is setup and run
+
+### Community contribution guidelines
+This guide should also include information for someone interested in asking questions,
+submitting issues or pull requests:
+
+* Any guidelines that you have in place for users submitting issues, pull requests or asking questions.
+* A link to your code of conduct
+* A link to or include how your code of conduct is enforced.
+
+```{note}
+[The mozilla open workshop has a nice outline of things to consider when
+creating a contributing guide](https://mozillascience.github.io/working-open-workshop/contributing/)
+```
+
+### License
+pyOpenSci projects should use an open source software license that is approved
+by the Open Software Initiative (OSI). OSI's website has a
+[list of popular licenses](https://opensource.org/licenses), and GitHub has a
+[handy tool](https://choosealicense.com/) for choosing a license.
+
+
\ No newline at end of file
diff --git a/documentation/create-readme-files.md b/documentation/create-readme-files.md
new file mode 100644
index 000000000..dce586e2a
--- /dev/null
+++ b/documentation/create-readme-files.md
@@ -0,0 +1,211 @@
+# README File Guidelines and Resources
+
+The **README.md** file is often the first thing that someone sees when they consider
+installing your package.
+
+This file is both the landing page of:
+
+* Your file on package manager landing pages like PyPI and Anaconda
+* Your package's GitHub repository
+
+Thus, it is important that you spend some time up front creating a high quality
+**README.md** file for your Python package.
+
+
+
+Your README.md file should be located in the root
+of your GitHub repository.
+
+
+
+## Organizing your README File from the most broad information to the most specific - Cognitive funneling
+
+We suggest organizing the content in your **README** file so that the most broad information is at the top of the file. Information then
+becomes more specific
+and potentially more technical as the user moves down the file.
+
+```{note}
+[Cognitive funneling approach](https://github.com/hackergrrl/art-of-readme#cognitive-funneling) refers to content structure where the most
+broad information is at the top and becomes increasingly more specific
+and possibly technical lower down in the file.
+```
+
+This approach of starting broad and progressively getting more specific
+will make your **README** file more accessible and easier-to-digest for a broader group of users. An overly complex or poorly organized **README**
+file will likely result in users getting lost, not understanding
+what your package does and how it could be useful to them.
+
+
+
+
+````{note}
+An editor or the editor in chief will ask you to revise your README file
+before a review begins if it does not meet the criteria specified below.
+
+Please go through this list before submitting your package to pyOpenSci
+
+```
+### pyOpenSci README checklist
+
+Your README file should have the following information:
+- [ ] The name of the package
+- [ ] Badges for the packages current published version, documentation and test suite build. (OPTIONAL: test coverage)
+- [ ] Easy-to-understand explanation (2-4 sentences) of what your tool does
+- [ ] Context for how the tool fits into the broader ecosystem
+- [ ] If it's your package is a wrapper, link to the package that it is wrapping and any associated documentation. (If you do'nt know what a wrapper is - this probably doesn't apply to you!)
+- [ ] A simple quickstart code example that a user can follow to provide a demonstration of what the package can do for them
+- [ ] Links to your packages documentation / website.
+- [ ] A few descriptive links to any tutorials you've created for your pacakge.
+```
+````
+
+A more detailed explanation of every element in this check list is below.
+
+## What your README.md file should contain (bare minimum)
+
+At a minimum, your package's **README.md** file should include
+(from top to bottom):
+
+### ✅ Your package's name
+Ideally your GitHub repository's name is also the name of your package. The more
+self explanatory that name is, the better.
+
+### ✅ Badges for current package version, continuous integration and test coverage
+
+Badges are a useful way to draw attention to the quality of your project and to
+assure users that your package is well-designed, tested, and maintained.
+It is common to provide a collection of badges towards the top of your
+README file for others to quickly browse.
+
+Some badges that you should adding to your README file include:
+
+* Current version of the package on pypi / conda forge (the example badge below provides a github release value in our package guide isn't an installable tool.)
+
+
+
+
+```markdown
+Github release
+
+```
+
+* Continuous integration Status of tests (pass or fail)
+
+Circle CI badge:
+[](https://circleci.com/gh/pyOpenSci/python-package-guide)
+
+Example GitHub actions badge:
+
+
+
+```
+
+```
+
+* Citation badge (DOI). It is OK if you do not have a DOI prior to the review. [](https://zenodo.org/badge/latestdoi/556814582)
+
+Once you package is accepted to pyOpenSci, we will provide you with
+a badge to add to your repository that shows that it has been reviewed and accepted into the pyOpenSci scientific Python open source ecosystem!
+
+
+
+```{note}
+Beware of the overuse of badges! There is such a thing as too much of a good thing (which can overload a potential user!).
+```
+
+### ✅ A short, easy-to-understand description of what your package does
+
+At the top of your README file you should have a short, easy-to-understand, description that details the goals of your package and what purpose it serves. The language in this description should use less technical terms so that a variety of users with varying scientific (and development) backgrounds can understand it.
+
+Consider writing for a 12th grade reading level which is an ideal level for more scientific content that serves a broad user base. The goal of this description to maximize accessibility of your **README** file.
+
+
+### ✅ BRIEF quickstart code demonstration of how to use the package
+
+Include a code quickstart that demonstrates how to use your package.
+This quickstart should be simple.
+
+```{important}
+### TOO MUCH OF A GOOD thing
+
+Try to avoid including several tutorials in the readme file itself. This too will overwhelm the user with information.
+
+A short quickstart vignette that shows a user how to use your package is plenty for the README file. All other tutorials and documentation should be presented as descriptive links.
+```
+
+### ✅ Descriptive links to package documentation, tutorials or vignettes.
+
+Include descriptive links in your README file to:
+
+* The package's documentation page.
+* Tutorials or vignettes that demonstrate application of your package.
+
+### ✅ Discussion of how this package fits within the broader scientific python landscape.
+
+If applicable, describe how the package compares to other similar packages or complementary packages in the scientific Python ecosystem. This discussion can be brief. It's important for package maintainers to consider their package in the context of the broader ecosystem. You will be asked to do this when you submit your package for review for pyOpenSci.
+
+### ✅ Installation instructions
+
+Include instructions for installing your package. If you have published
+the package on both `PyPI` and `Conda` be sure to include instructions for both.
+
+### ✅ Document any addition setup required to use you package
+
+Add any additional setup required that someone will need to do before using your package. Examples of additional setup steps including authentication tokens, or critical dependencies that don't get automatically installed when your package is installed.
+
+### ✅ Citation information
+
+Finally be sure to include instructions on how to cite your package.
+
+### ✅ Links to Contributing Guide, Code of Conduct
+Last but not least provide direct links to your
+**CONTRIBUTING** guide and to your project's **code of conduct**.
+
+
+```{note}
+### README Resources
+
+Below are some resources on creating great README.md files that you
+might find helpful.
+
+* [The art of the README GitHub Repo](https://github.com/hackergrrl/art-of-readme)
+* [Write a great readme - Bane Sullivan](https://github.com/banesullivan/README)
+* [Readme resources from rOpenSci](https://devguide.ropensci.org/building.html#readme)
+```
+
+
+
+
diff --git a/documentation/index.md b/documentation/index.md
new file mode 100644
index 000000000..97f45dd17
--- /dev/null
+++ b/documentation/index.md
@@ -0,0 +1,46 @@
+# Intro: Document Your Python Package
+
+```{attention}
+🚧 UNDER CONSTRUCTION - THIS CONTENT SHOULD BE FURTHER DEVELOPED BY THE END OF 2022! KEEP CHECKING BACK TO UPDATES AS THEY ARE IN PROGRESS🚧
+```
+## Documentation is critical to the success of your Python open source package
+
+Documentation is as important to the success of your Python open source package
+as the code itself. While quality code is valuable as it gets the tasks that your
+package seeks to achieve, completed, if users don't understand how to use the
+tools in your package then they won't use your tool.
+
+## Documentation elements that we look for when reviewing a Python package
+
+In the pyOpenSci peer review process we look for several things when evaluating
+package documentation including:
+
+1. A clear and to the point **README.md** file
+2. Documentation of the functionality of your code. This is often setup using Sphinx/ Read the docs or some other documentation platform
+3. Sufficient API documentation of your packages API (this means that docstrings are formatted with explanations of each variable and better yet quick vignettes that demonstrate how to use the function or class). If you don't know what API documentation means this section is FOR YOU!
+4. A **CONTRIBUTING.md** file that has clear instructions that others can follow to setup a development environment. This will support others contributing to your project.
+5. A license file that helps people
+
+
+
+
+
+
+
+
+
+
diff --git a/documentation/package-documentation-tutorials.md b/documentation/package-documentation-tutorials.md
new file mode 100644
index 000000000..30d16870b
--- /dev/null
+++ b/documentation/package-documentation-tutorials.md
@@ -0,0 +1,158 @@
+# Python Package Documentation
+
+```{note}
+Examples of documentation that we love:
+
+* [geopandas](https://geopandas.org/en/stable/)
+ * [View rst to create landing page](https://raw.githubusercontent.com/geopandas/geopandas/main/doc/source/index.rst)
+* [verde](https://www.fatiando.org/verde/latest/)
+ * [View verde landing page code - rst file.](https://github.com/fatiando/verde/blob/main/doc/index.rst)
+* [Here is our documentation if you want to see a myST example of a landing page.](https://github.com/pyOpenSci/python-package-guide/blob/main/index.md)
+```
+
+
+## Package documentation
+
+Your package should have user-facing and API focused documentation. We suggest
+that you setup a website to host your documentation.
+Many prefer to use Sphinx to create
+their Python package documentation. Sphinx is a useful tool as it offers extensions
+that support things like:
+
+* [automatically documenting your API using docstrings](https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html)
+* running and testing code examples in your docstrings
+
+## Documentation landing page best practices
+
+To make it easy for users to find what they need quickly, all packages should
+have 4 elements on the home page of their documentation:
+
+* **Getting started:** This section should provide the user with a quick start for installing your package. A small example of how to use the package is good to have here as well.
+* **About:** Describe your project, state project goals and what it does.
+* **Community:** Instructions for ho to help and/or get involved. This section might include a development guide.
+* **Documentation:** The actual project documentation. You may have two sections of documentation - the user facing documentation and your API reference.
+
+NOTE: in many cases you can include your **README** file and your **CONTRIBUTING** files
+in your documentation given those files may have some of the components listed above.
+Some packages
+
+### Sphinx themes
+Sphinx also offers numerous themes that you can use to customize your documentation.
+A few Sphinx themes that are commonly used in the Scientific Python community that you might
+consider include:
+
+* [pydata sphinx theme](https://pydata-sphinx-theme.readthedocs.io/en/stable/)
+* [sphinx book theme](https://sphinx-book-theme.readthedocs.io/en/stable/)
+
+This contributing guide is created using a modified version of the Spinx Book
+theme.
+
+### myST vs rst syntax to create your docs
+There are two commonly used syntaxes for creating docs:
+
+1. [myST:](https://myst-parser.readthedocs.io/en/latest/intro.html) myST is a fusion of markdown and rST. It is a nice option if you are more comfortable writing markdown. But more flexible than markdown.
+2. [rST:](https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html) this is the native syntax that sphinx supports.
+
+There is no wrong or right when choosing a syntax to write your documentation.
+Choose whichever syntax works best for you and your community!
+
+```{note}
+If you are on the fence about myST vs rst, you might find that *myST* is easier
+for more people to contribute to.
+```
+
+
+### Publish your docs on another platform directly from GitHub: ReadTheDocs.org
+
+If you don't want to maintain a documentation website for your Python package, we
+suggest using the [READTHEDOCS platform](https://www.readthedocs.org) which
+allows you to easily host your documentation and track versions of your docs
+as you release updates.
+
+Beyond a well designed [README FILE](create-readme-files) there are several
+core components of Python package documentation including:
+
+1. User facing documentation
+2. API documentation
+
+## User-facing documentation for your Python package:
+
+User-facing documentation is often an easy to navigate website written with
+user friendly, less technical language. User facing documentation should be:
+
+* easy to read (consider writing for a 12th grade audience)
+* contain tutorials or vignettes that support getting started using your package
+
+
+## Python package API documentation
+
+API documentation refers to explanation about the function, inputs and outputs
+of every (*within reason*) function, class, method in your package. API documentation
+in python requires that you use a docstring for each class, function or method that:
+
+* Explains what the function, method or class does
+* Explains what every input and output variable's (type) is (ie. `string`, `int`, `np.array`)
+* Explains the expected output `return` of the object, method or function.
+
+
+### Docstring examples Better and Best
+
+Below is a good example of a well documented function. Notice that this function's
+docstring includes all parameter inputs and outputs. The description of the function
+is short and to the point (2 to 3 sentences). And the return of the function is
+specified.
+
+```Python
+def extent_to_json(ext_obj):
+ """Convert bounds to a shapely geojson like spatial object.
+ This format is what shapely uses. The output object can be used
+ to crop a raster image.
+ Parameters
+ ----------
+ ext_obj: list or geopandas geodataframe
+ If provided with a geopandas geodataframe, the extent
+ will be generated from that. Otherwise, extent values
+ should be in the order: minx, miny, maxx, maxy.
+ Return
+ ------
+ extent_json: A GeoJSON style dictionary of corner coordinates
+ for the extent
+ A GeoJSON style dictionary of corner coordinates representing
+ the spatial extent of the provided spatial object.
+ """
+```
+
+### Best - a docstring with example use of the function
+
+This example contains an example of using the function that is also tested in
+sphinx using [doctest](https://docs.python.org/3/library/doctest.html).
+
+```Python
+def extent_to_json(ext_obj):
+ """Convert bounds to a shapely geojson like spatial object.
+ This format is what shapely uses. The output object can be used
+ to crop a raster image.
+ Parameters
+ ----------
+ ext_obj: list or geopandas geodataframe
+ If provided with a geopandas geodataframe, the extent
+ will be generated from that. Otherwise, extent values
+ should be in the order: minx, miny, maxx, maxy.
+ Return
+ ------
+ extent_json: A GeoJSON style dictionary of corner coordinates
+ for the extent
+ A GeoJSON style dictionary of corner coordinates representing
+ the spatial extent of the provided spatial object.
+ Example
+ -------
+ >>> import geopandas as gpd
+ >>> import earthpy.spatial as es
+ >>> from earthpy.io import path_to_example
+ >>> rmnp = gpd.read_file(path_to_example('rmnp.shp'))
+ >>> es.extent_to_json(rmnp)
+ {'type': 'Polygon', 'coordinates': (((-105.4935937, 40.1580827), ...),)}
+ """
+
+```
+
diff --git a/images/logo/download.svg b/images/logo/download.svg
new file mode 100644
index 000000000..ab2550874
--- /dev/null
+++ b/images/logo/download.svg
@@ -0,0 +1,90 @@
+
diff --git a/images/logo/favicon.ico b/images/logo/favicon.ico
new file mode 100644
index 000000000..eb2cf42e7
Binary files /dev/null and b/images/logo/favicon.ico differ
diff --git a/images/logo/logo.png b/images/logo/logo.png
new file mode 100644
index 000000000..ea39fc27e
Binary files /dev/null and b/images/logo/logo.png differ
diff --git a/images/logo/logo.psd b/images/logo/logo.psd
new file mode 100644
index 000000000..d6ad942b7
Binary files /dev/null and b/images/logo/logo.psd differ
diff --git a/index.md b/index.md
index 42cdad134..2c73e7b10 100644
--- a/index.md
+++ b/index.md
@@ -1,6 +1,11 @@
-# Welcome to the pyOpenSci Python Package Development Guide
+# pyOpenSci Python Open Source Package Development Guide
-## pyOpenSci provides recommendations and a curated list of community resources that Python package infrastructure for the scientific community.
+
+## Welcome, Python open source enthusiast!
+
+Here you will find guidelines for what we look for in your scientific
+Python package when reviewing. You will also find best practice recommendations and curated lists of community resources surrounding packaging and documentation.
::::{grid} 2
:reverse:
@@ -27,7 +32,8 @@ Removing button for the time being
Get Involved (Maybe a link to a get involved page)
% SVG rendering breaks latex builds for the GitHub badge, so only include in HTML
-``` -->
+```
+-->
```{only} html
@@ -46,7 +52,7 @@ Get Involved (Maybe a link to a get involved page)
:gutter: 3
:::{grid-item-card}
-:link: documentation/intro
+:link: documentation/index
:link-type: doc
:class-header: bg-light
@@ -63,23 +69,32 @@ covered include: README files, tutorials and full docs.
:link-type: doc
:class-header: bg-light
-✨Code style and structure✨
+✨ Coming soon... ✨
^^^
-Get a basic overview of our open peer review process for Python scientific open source software.
+
:::
-::::
-
+:::{grid-item-card}
+:link: CONTRIBUTING
+:link-type: doc
+:class-header: bg-light
-### Python Packaging Guide for Maintainers Submitting to PyOpenSci
+✨ Want to contribute? ✨
+^^^
+We welcome contributions to this guide. Learn more about how you can
+contribute.
+:::
+::::
-Welcome to pyOpenSci! We assume you are here because
+## Who this guidebook is for
+We assume that you are here because you are:
-1. you are considering submitting a package to pyOpenSci and want to understand the best practices that we suggest
-2. You are looking for guidance on creating your first Python package.
-3. Or you're just looking for resources associated with Python packaging.
+1. Considering submitting a package to pyOpenSci and want to understand what we are looking for when we review your package
+2. Looking for guidance on creating a Python package.
+3. Looking for resources associated with Python packaging.
-Well, my friend you've come to the right place!
+Well, friend, you've come to the right place!
## What you will find in this guidebook
@@ -89,30 +104,35 @@ This guidebook contains:
* Explanation of better and best practices in case you want to set the bar higher for your package (which we hope you will)!
* A curated list of resources to help you get your package into documented, usable and tested shape.
+## Where this guide is headed
+
+Most of the sections in this guide will ultimately include Good/Better/Best recommendations for Python open source software packaging.
+
+Good meets the requirements. Going beyond the minimum can make package maintenance easier-to-use for new users, easier-to contribute for new contributors and easier-to-maintain for you.
-Most of the sections also include Good/Better/Best recommendations.
-Good meets the requirements, but going beyond the minimum can make package maintenance easier-to-use for new users, easier-to contribute for new contributors and easier-to-maintain for you.
+This guide is now a work in progress. If you have ideas of things you'd like
+to see here, [we invite you to open an issue on GitHub that details any changes or additions that you'd like to see.](https://github.com/pyOpenSci/python-package-guide/issues).
```{toctree}
:hidden:
:caption: Documentation
-documentation/intro
-documentation/readme-files
-documentation/package-documentation-tutorials
+Intro to Documentation
+The README File
+Package docs & tutorials
+Contributing & license files
```
```{toctree}
:hidden:
-:caption: Code Style & Structure
-
-code-style-structure/intro
+:caption: Package structure
+I don't work
+I work
```
```{toctree}
:hidden:
:caption: Test your code
-
testing-infrastructure/test-code
testing-infrastructure/continuous-integration
```
@@ -127,3 +147,35 @@ Get Involved (Maybe a link to a get involved page)
``` -->
+
+
pyOpenSci Packaging Guide
+#