sphinx-doc/sphinx

Specifying copyright on a file-by-file basis

Closed

#6,599 opened on Jul 23, 2019

View on GitHubContributor guide
 (1 comment) (0 reactions) (0 assignees)Python (1,985 forks)batch import
awaiting:responsehelp wantedtype:enhancement

Repository metrics

Stars
 (5,625 stars)
PR merge metrics
 (Avg merge 10d 11h) (11 merged PRs in 30d)

Description

Is your feature request related to a problem? Please describe.

My project has a lot of legacy content written by many contributors, so the copyright on those pages is fixed. I'd like to use Creative Commons licenses for new content. Unfortunately, it seems as though Sphinx can only be configured with a single copyright value, applied to all documents.

Describe the solution you'd like

Would the maintainers accept a new feature to override the copyright string on a per-file basis? It seems as though Sphinx's file-wide metadata would be the appropriate place to implement this, but maybe there's a better way.

Describe alternatives you've considered

I could fork the HTML template I am using and modify it to ignore the built-in "copyright" configuration and render the value of a custom variable. I'd rather not take on the burden of maintaining such a template. That would be especially taxing if the project's documentation were to target additional output formats.

Contributor guide

Research direction
Investigate the current implementation of file wide metadata in Sphinx (http://www.sphinx doc.org/en/master/usage/restructuredtext/field lists.html). Examine how the 'copyright' configuration is applied globally in templates (e.g., in the HTML builder). Look for any existing discussions or attempts in linked PRs or comments. The issue has only one comment, so review that for additional context. Consider proposing a design that overrides the copyright string per file via metadata, ensuring compatibility with multiple output formats.
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.
3
Estimated timeA rough time range for an experienced contributor to investigate, implement, test, and prepare a pull request.
1-2 days
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
Knowledge of Sphinx configurationUnderstanding of reStructuredText field lists
Newbie friendlinessA 1-100 score estimating how approachable this issue is for first-time contributors.
40