Skip to content

Commit b682238

Browse files
lwasserlwasser
authored
INFRA: add sphinx book infra to build 🍾 (#1)
* add infra to build sphinx book * adding * Remove html proofer just for now 🍾 * remove more files
1 parent 44ab4b8 commit b682238

File tree

8 files changed

+346
-10
lines changed

8 files changed

+346
-10
lines changed

‎.github/workflows/build-book.yml

-8
Original file line numberDiff line numberDiff line change
@@ -37,14 +37,6 @@ jobs:
3737
- name: Build book
3838
run: nox -s docs
3939

40-
# Test for bad links and ensure alt tags for usability
41-
- name: Check HTML using htmlproofer
42-
uses: chabad360/htmlproofer@master
43-
with:
44-
directory: '_build'
45-
arguments: |
46-
--ignore-files "/.+\/_static/"
47-
4840
# Save html as artifact
4941
- name: Save book html as artifact for viewing
5042
uses: actions/upload-artifact@v3

‎README.md

+65-2
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,65 @@
1-
# python-packaging-guide
2-
A guide with scientific python package recommendations curated by pyOpenSci
1+
# <img src="images/logo/logo.png" width=40 /> pyOpenSci Governance
2+
3+
![GitHub release (latest by date)](https://img.shields.io/github/v/release/pyopensci/python-package-guide?color=purple&display_name=tag&style=plastic)
4+
5+
[![DOI](https://zenodo.org/badge/556814582.svg)](https://zenodo.org/badge/latestdoi/556814582)
6+
7+
[![CircleCI](https://circleci.com/gh/pyOpenSci/python-package-guide.svg?style=svg)](https://circleci.com/gh/pyOpenSci/python-package-guide)
8+
9+
## What is pyOpenSci?
10+
11+
pyOpenSci is devoted to building diverse, supportive community around
12+
the Python open source tools that drive open science. We do this through:
13+
14+
* open peer review
15+
* mentorship and
16+
* training.
17+
18+
pyOpenSci is an independent organization, fiscally sponsored by Community
19+
Initiatives.
20+
21+
:construction: Construction note :construction:
22+
23+
This repository is currently under heavy construction. So please note that if
24+
you are working through the content!
25+
26+
## Contributing statement
27+
28+
29+
## How to setup
30+
31+
This repository contains the source files for the [pyOpenSci governance](https://pyopensci.org/governance).
32+
33+
## Build the governance document locally
34+
35+
Our governance documentation is built with [Sphinx](https://sphinx-doc.org) which is a documentation tool.
36+
37+
The easiest way to build our documentationis to use [the `nox` automation tool](https://nox.thea.codes/), a tool for quickly building environments and running commands within them.
38+
Using `nox` ensures that your environment has all the dependencies needed to build the documentation.
39+
40+
To build, follow these steps:
41+
42+
1. Install `nox`
43+
44+
```console
45+
$ pip install nox
46+
```
47+
2. Build the documentation:
48+
49+
```console
50+
$ nox -s docs
51+
```
52+
53+
This should create a local environment in a `.nox` folder, build the documentation (as specified in the `noxfile.py` configuration), and the output will be in `_build/html`.
54+
55+
To build live documentation that updates when you update local files, run the following command:
56+
57+
```console
58+
$ nox -s docs-live
59+
```
60+
61+
62+
## Contributing to this guide
63+
64+
We welcome and issues and pull-requests to improve the content of this guide.
65+
If you'd like to see an improvement, please [open an issue](https://github.com/pyOpenSci/governance/issues/new/choose).

‎_config.yml

+24
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
# Book settings
2+
title: The pyOpenSci Developer Guide
3+
author: The pyOpenSci Community
4+
logo: images/logo/logo.png
5+
exclude_patterns: ["README.md"]
6+
7+
repository:
8+
url: https://github.com/pyOpenSci/contributing-guide
9+
branch: main
10+
11+
html:
12+
favicon: images/logo/logo.png
13+
google_analytics_id: UA-141260825-1
14+
use_edit_page_button: true
15+
use_issues_button: true
16+
use_repository_button: true
17+
home_page_in_navbar: false
18+
announcement: "<div class='header__block'>ATTENTION
19+
<p>
20+
We are currently updating this book to stay tuned!
21+
The content should become more stable in early 2023.
22+
</p>
23+
</div>
24+
"

‎code-style-structure/intro.md

+4
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
# Code style and structure
2+
3+
4+
Under development

‎conf.py

+88
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,88 @@
1+
# Configuration file for the Sphinx documentation builder.
2+
#
3+
# This file only contains a selection of the most common options. For a full
4+
# list see the documentation:
5+
# https://www.sphinx-doc.org/en/master/usage/configuration.html
6+
7+
# -- Path setup --------------------------------------------------------------
8+
9+
# If extensions (or modules to document with autodoc) are in another directory,
10+
# add these directories to sys.path here. If the directory is relative to the
11+
# documentation root, use os.path.abspath to make it absolute, like shown here.
12+
#
13+
# import os
14+
# import sys
15+
# sys.path.insert(0, os.path.abspath('.'))
16+
17+
18+
# -- Project information -----------------------------------------------------
19+
20+
project = 'python-package-guide'
21+
copyright = '2022, pyOpenSci'
22+
author = 'Leah Wasser'
23+
24+
# The full version, including alpha/beta/rc tags
25+
release = '0.1'
26+
27+
28+
# -- General configuration ---------------------------------------------------
29+
30+
# Add any Sphinx extension module names here, as strings. They can be
31+
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
32+
# ones.
33+
extensions = [
34+
"myst_nb",
35+
# "myst_parser",
36+
"sphinx_design",
37+
"sphinx_copybutton",
38+
"sphinx.ext.intersphinx"
39+
]
40+
41+
# colon fence for card support in md
42+
myst_enable_extensions = ["colon_fence"]
43+
44+
45+
# Link to our repo for easy PR/ editing
46+
html_theme_options = {
47+
"repository_url": "https://github.com/pyopensci/python-package-guide",
48+
"use_repository_button": True,
49+
"google_analytics_id": "UA-141260825-1",
50+
"external_links": [
51+
{"name": "link-one-name", "url": "https://www.pyopensci.org"},
52+
{"name": "link-two-name", "url": "https://pyopensci.org"}
53+
],
54+
"announcement": "🚧 UNDER CONSTRUCTION: this guide is under heavy construction right now. 🚧"
55+
}
56+
57+
58+
59+
# Add any paths that contain templates here, relative to this directory.
60+
templates_path = ['_templates']
61+
62+
# List of patterns, relative to source directory, that match files and
63+
# directories to ignore when looking for source files.
64+
# This pattern also affects html_static_path and html_extra_path.
65+
exclude_patterns = [
66+
"_build",
67+
"Thumbs.db",
68+
".DS_Store",
69+
".github",
70+
".nox",
71+
"README.md"
72+
]
73+
74+
75+
# -- Options for HTML output -------------------------------------------------
76+
77+
# The theme to use for HTML and HTML Help pages. See the documentation for
78+
# a list of builtin themes.
79+
#
80+
html_theme = 'sphinx_book_theme'
81+
html_static_path = ["_static"]
82+
html_title = "pyOpenSci Package Guide"
83+
html_logo = "images/logo/logo.png"
84+
85+
# Add any paths that contain custom static files (such as style sheets) here,
86+
# relative to this directory. They are copied after the builtin static files,
87+
# so a file named "default.css" will overwrite the builtin "default.css".
88+
html_static_path = ['_static']

‎index.md

+129
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,129 @@
1+
# Welcome to the pyOpenSci Python Package Development Guide
2+
3+
## pyOpenSci provides recommendations and a curated list of community resources that Python package infrastructure for the scientific community.
4+
5+
::::{grid} 2
6+
:reverse:
7+
8+
:::{grid-item}
9+
:columns: 4
10+
:class: sd-m-auto
11+
12+
:::
13+
14+
:::{grid-item}
15+
:columns: 8
16+
:class: sd-fs-3
17+
18+
19+
<!--
20+
Removing button for the time being
21+
```{button-ref} start/your-first-book
22+
:ref-type: doc
23+
:color: primary
24+
:class: sd-rounded-pill float-left
25+
26+
27+
Get Involved (Maybe a link to a get involved page)
28+
29+
% SVG rendering breaks latex builds for the GitHub badge, so only include in HTML
30+
``` -->
31+
32+
```{only} html
33+
![GitHub release (latest by date)](https://img.shields.io/github/v/release/pyopensci/python-package-guide?color=purple&display_name=tag&style=plastic)
34+
[![](https://img.shields.io/github/stars/pyopensci/python-package-guide?style=social)](https://github.com/pyopensci/contributing-guide)
35+
[![DOI](https://zenodo.org/badge/556814582.svg)](https://zenodo.org/badge/latestdoi/556814582)
36+
```
37+
38+
:::
39+
::::
40+
41+
42+
<!-- I think this is the end of the header - below begins the next grid-->
43+
44+
::::{grid} 1 1 1 2
45+
:class-container: text-center
46+
:gutter: 3
47+
48+
:::{grid-item-card}
49+
:link: documentation/intro
50+
:link-type: doc
51+
:class-header: bg-light
52+
53+
✨ Documentation Criteria & Recommendations ✨
54+
^^^
55+
56+
Learn about the good, better and best practices
57+
associated with Python package documentation. Topics
58+
covered include: README files, tutorials and full docs.
59+
:::
60+
61+
:::{grid-item-card}
62+
:link: code-style-structure/intro
63+
:link-type: doc
64+
:class-header: bg-light
65+
66+
✨Code style and structure✨
67+
^^^
68+
Get a basic overview of our open peer review process for Python scientific open source software.
69+
:::
70+
71+
::::
72+
73+
74+
### Python Packaging Guide for Maintainers Submitting to PyOpenSci
75+
76+
Welcome to pyOpenSci! We assume you are here because
77+
78+
1. you are considering submitting a package to pyOpenSci and want to understand the best practices that we suggest
79+
2. You are looking for guidance on creating your first Python package.
80+
3. Or you're just looking for resources associated with Python packaging.
81+
82+
Well, my friend you've come to the right place!
83+
84+
## What you will find in this guidebook
85+
86+
This guidebook contains:
87+
88+
* Explanation for "Good enough" minimum requirements associated with being reviewed by pyOpenSci
89+
* Explanation of better and best practices in case you want to set the bar higher for your package (which we hope you will)!
90+
* A curated list of resources to help you get your package into documented, usable and tested shape.
91+
92+
93+
Most of the sections also include Good/Better/Best recommendations.
94+
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.
95+
96+
```{toctree}
97+
:hidden:
98+
:caption: Documentation
99+
100+
documentation/intro
101+
documentation/readme-files
102+
documentation/package-documentation-tutorials
103+
```
104+
105+
```{toctree}
106+
:hidden:
107+
:caption: Code Style & Structure
108+
109+
code-style-structure/intro
110+
```
111+
112+
```{toctree}
113+
:hidden:
114+
:caption: Test your code
115+
116+
testing-infrastructure/test-code
117+
testing-infrastructure/continuous-integration
118+
```
119+
120+
<!--
121+
Removing button for the time being
122+
```{button-ref} start/your-first-book
123+
:ref-type: doc
124+
:color: primary
125+
:class: sd-rounded-pill float-left
126+
Get Involved (Maybe a link to a get involved page)
127+
``` -->
128+
129+

‎noxfile.py

+28
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
import nox
2+
3+
nox.options.reuse_existing_virtualenvs = True
4+
5+
build_command = ["-b", "html", ".", "_build/html"]
6+
7+
@nox.session
8+
def docs(session):
9+
session.install("-r", "requirements.txt")
10+
cmd = ["sphinx-build"]
11+
cmd.extend(build_command + session.posargs)
12+
session.run(*cmd)
13+
14+
15+
@nox.session(name="docs-live")
16+
def docs_live(session):
17+
session.install("-r", "requirements.txt")
18+
19+
AUTOBUILD_IGNORE = [
20+
"_build",
21+
"build_assets",
22+
"tmp",
23+
]
24+
cmd = ["sphinx-autobuild"]
25+
for folder in AUTOBUILD_IGNORE:
26+
cmd.extend(["--ignore", f"*/{folder}/*"])
27+
cmd.extend(build_command + session.posargs)
28+
session.run(*cmd)

‎requirements.txt

+8
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
#ipython
2+
sphinx-book-theme
3+
myst-parser[linkify]
4+
myst-nb
5+
sphinx
6+
sphinx-autobuild
7+
sphinx-copybutton
8+
sphinx-design

0 commit comments

Comments
 (0)