Skip to content

Commit 293785f

Browse files
nedbatwillingc
nedbat
and
willingc
authored
Flesh out the Contributor's Guide (#1426)
A start on the new organization turning the devguide into a Contributor's Guide. Co-authored-by: Carol Willing <carolcode@willingconsulting.com>
1 parent 5028ad3 commit 293785f

32 files changed

+503
-1
lines changed

‎Makefile‎

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,12 @@ PYTHON = python3
66
VENVDIR = ./venv
77
UV = uv
88
SPHINXBUILD = $(VENVDIR)/bin/sphinx-build
9-
SPHINXOPTS = --fail-on-warning --keep-going
9+
# Temporary: while we are using ..include:: to show the reorganization,
10+
# there are duplicate labels. These cause warnings, which prevent the
11+
# build from finishing. Turn off --fail-on-warning so we can see the
12+
# finished results.
13+
#SPHINXOPTS = --fail-on-warning --keep-going
14+
SPHINXOPTS = --keep-going
1015
BUILDDIR = _build
1116
BUILDER = html
1217
JOBS = auto

‎conf.py‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -171,6 +171,26 @@
171171
# sphinx-notfound-page
172172
notfound_urls_prefix = "/"
173173

174+
# prolog and epilogs
175+
rst_prolog = """
176+
.. |draft| replace::
177+
This is part of a **Draft** of the Python Contributor's Guide.
178+
Text in square brackets are notes about content to fill in.
179+
Currently, the devguide and this new Contributor's Guide co-exist in the
180+
repo. We are using Sphinx include directives to demonstrate the re-organization.
181+
The final Contributor's Guide will replace the devguide with content in only one
182+
place.
183+
We welcome help with this!
184+
185+
.. |purpose| replace::
186+
The :ref:`contrib-plan` page has more details about the current state of this draft
187+
and **how you can help**. See more info about the Contributor Guide in the
188+
discussion forum: `Refactoring the DevGuide`_.
189+
190+
.. _Refactoring the DevGuide: https://discuss.python.org/t/refactoring-the-devguide-into-a-contribution-guide/63409
191+
192+
"""
193+
174194
# sphinx.ext.extlinks
175195
# This config is a dictionary of external sites,
176196
# mapping unique short aliases to a base URL and a prefix.

‎contrib/code/index.rst‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
==================
2+
Code contributions
3+
==================
4+
5+
.. important::
6+
7+
|draft|
8+
9+
|purpose|
10+
11+
* Code setup and building (more complex stuff, delta from basic setup above)
12+
* More git bootcamp (patches, etc)
13+
* Lifecycle of a code pull request
14+
* Development workflow (from devguide)
15+
* Testing and buildbots (from devguide)
16+
* Development tools (from devguide)
17+
* CPython’s internals (from devguide)
18+
* Code style guide

‎contrib/contrib-plan.rst‎

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
.. _contrib-plan:
2+
3+
================================
4+
Plan for the Contributor's Guide
5+
================================
6+
7+
.. important::
8+
9+
|draft|
10+
11+
|purpose|
12+
13+
We are in the process of updating and refactoring the devguide to be a
14+
Contributor's Guide. It will highlight the different kinds of contribution
15+
possible, and how to succeed at each kind.
16+
17+
Currently, the Contibutor's Guide is a draft in this new last section of the
18+
devguide. We welcome feedback, but please understand that some of the current
19+
content is moving or skeletal.
20+
21+
Repo structure
22+
==============
23+
24+
While the reorganization is happening, we are keeping the old devguide as it
25+
is. The new Contributor's Guide is represented in this last section, but will
26+
eventually be the only content in the guide. To avoid copying content, we're
27+
using Sphinx include directives to display existing devguide content in its new
28+
Contributor's Guide location. That is not how the eventual Guide will be
29+
built. Once we are ready to make the Contributor's Guide real, we will
30+
rearrange content into its new location.
31+
32+
How to help
33+
===========
34+
35+
To help, you can:
36+
37+
- `Write an issue`_ detailing a change you'd like to see here.
38+
- `Make a pull request`_ in this repo to add content.
39+
- Join us in the `Python Docs Discord`_ to collaborate with other docs-minded
40+
community members.
41+
- Get in touch with the `Docs Editorial Board`_ to discuss larger documentation
42+
concerns.
43+
44+
.. _Write an issue: https://github.com/python/devguide/issues
45+
.. _Make a pull request: https://github.com/python/devguide/pulls
46+
.. _Python Docs Discord: https://discord.gg/NeGgyhUZ
47+
.. _Docs Editorial Board: https://python.github.io/editorial-board/

‎contrib/doc/index.rst‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
===========================
2+
Documentation contributions
3+
===========================
4+
5+
.. important::
6+
7+
|draft|
8+
9+
|purpose|
10+
11+
12+
* Lifecycle of a docs pull request
13+
* (pull in Documentation sections from devguide)
14+
* Rst/Sphinx bootcamp
15+
* Editorial Style Guide
16+
* Translation
17+
- How to add a new language
18+
- Tools and workflow

‎contrib/get-started/index.rst‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
===============
2+
Getting started
3+
===============
4+
5+
.. important::
6+
7+
|draft|
8+
9+
|purpose|
10+
11+
12+
* Basic setup
13+
* Git bootcamp (simplified for everyone to use)

‎contrib/index.rst‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
==================================
2+
Python Contributor's Guide (draft)
3+
==================================
4+
5+
.. important::
6+
7+
|draft|
8+
9+
|purpose|
10+
11+
12+
This guide is a comprehensive resource for contributing to Python.
13+
14+
.. note::
15+
This is a draft of a new organization for the devguide, turning it into a
16+
Contributor's Guide.
17+
18+
[Much of the devguide home page will be here. The Quick Start will be updated
19+
to distinguish code vs documentation contributions, and moved to those
20+
sections. Other changes will be made to explain the different types of
21+
contribution and how to navigate the guide for your own type.]
22+
23+
24+
.. toctree::
25+
:maxdepth: 2
26+
27+
contrib-plan
28+
intro/index
29+
project/index
30+
get-started/index
31+
triage/index
32+
code/index
33+
doc/index
34+
user-success
35+
security
36+
outreach

‎contrib/intro/index.rst‎

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
============
2+
Introduction
3+
============
4+
5+
.. important::
6+
7+
|draft|
8+
9+
|purpose|
10+
11+
12+
13+
14+
Welcome!
15+
16+
Healthy Collaboration
17+
=====================
18+
19+
[Importance of healthy inclusive collaboration]
20+
21+
[While code is a large part of the project's success, project management, documentation, governance, sprint outreach, etc. matter.]
22+
23+
[We respect the individual skills people bring to the project and strive to create and maintain a culture of inclusion.]
24+
25+
About this Guide
26+
================
27+
28+
Types of Contribution
29+
=====================
30+
31+
[Pathways for contributors]
32+
33+
Helping with this Guide
34+
=======================

‎contrib/outreach.rst‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
========
2+
Outreach
3+
========
4+
5+
.. important::
6+
7+
|draft|
8+
9+
|purpose|
10+
11+
12+
* Sprints

‎contrib/project/channels.rst‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
.. important::
2+
3+
|draft|
4+
5+
|purpose|
6+
7+
8+
======================
9+
Communication channels
10+
======================
11+
12+
* Repos
13+
* Discourse
14+
* Discord
15+
* Mailing lists (deprioritize)
16+
* Where to get help

0 commit comments

Comments
 (0)