sphinx-doc/sphinx

Feature Request: Add sample page with formatting when quickstart project

Open

#4,731 opened on Mar 12, 2018

View on GitHub
 (2 comments) (2 reactions) (0 assignees)Python (5,625 stars) (1,985 forks)batch import
api:cmdlinehelp wantedtype:proposal

Description

The open source project I help with are looking at Sphinx to replace our mediawiki install.

I have been trying to learn how to get it going and the biggest confusion I ran into was how to add pages and doing text formatting. There is a fair amount of documentation online, but much of it is written for older versions of Sphinx which make it confusing to know what is useful.

Feature: Have a sample page (not toc) that has a variety of reStructuredText formatting examples in it.

Not only can this help people learn how sphinx structures files in the toc, but this also makes it easier for theme developers. If I want to do theming, I can easily see a lot of the variation that might appear as an author is writing stuff down.

Contributor guide

Tech stack
python
Domain
documentation
Issue type
feature
DifficultyEstimated implementation difficulty for a new contributor, from 1 for very small changes to 5 for expert-level work.
2
Estimated timeA rough time range for an experienced contributor to investigate, implement, test, and prepare a pull request.
1-3 hours
Activity statusHow available the issue appears right now: fresh, active, stale, blocked, or waiting on maintainer input.
stale
ClarityHow clearly the issue explains the expected change, acceptance criteria, and next step.
clear
Prerequisites
Basic reStructuredTextSphinx quickstart structure
Newbie friendlinessA 1-100 score estimating how approachable this issue is for first-time contributors.
75
Research direction
Create a new reStructuredText file with formatting examples (headings, lists, code blocks, tables) and integrate it into the Sphinx quickstart template. The relevant code is in `sphinx/quickstart.py` where default files are created. No existing PRs or maintainer comments provide additional guidance.