CONTENT: documentation text and styles

.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

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.

README.md

@@ -1,4 +1,4 @@
-# <img src="images/logo/logo.png" width=40 /> pyOpenSci Packaging Guide
+# <img src="images/logo/logo.png" width=40 /> pyOpenSci Scientific Python Open Source Packaging Guide
 
 ![GitHub release (latest by date)](https://img.shields.io/github/v/release/pyopensci/python-package-guide?color=purple&display_name=tag&style=plastic)
 

_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;
+}

_templates/header.html

@@ -0,0 +1,7 @@
+<!-- custom head content-->
+
+<!-- <link rel="preconnect" href="https://fonts.googleapis.com">
+<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+<link href="https://fonts.googleapis.com/css2?family=Open+Sans:wght@400;600&family=Raleway:wght@200;300;400;600&display=swap" rel="stylesheet">  -->
+<!-- END custom head content --> 
+

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"
 

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.
+
+<!-- 
+pyOpenSci packages must:
+
+- Contain full documentation for any user-facing functions.
+- Have a test suite that covers the major functionality of the package.
+- Use continuous integration.
+- Use an OSI approved software license.
+
+**Good/Better/Best:**
+- **Good:** Include a open source software license with your package.
+- **Better/Best:** Choose a license based on your needs and future use of package, plus explain your choice in your submission for review. -->