sphinx-doc / sphinx-doc/sphinx

Configure static output directory for css, js and images and everything else

Open
#11,032 1 comment 2 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

builder:html internals:config type:proposal
Dominant language
Python
Stars
8k
Forks
2.6k
PR merge metrics
No merged PRs in 30d

Description

Hi,

I've seen many topics about the subject of static files in Sphinx (For example this one https://github.com/sphinx-doc/sphinx/issues/2202 or even this one https://github.com/introt/docs/issues/2)

I have to be able to set the path of images, js and styles wherever I want them to be.

For example, my documentation will be on the same domain of my app but prefixed by 'docs' like this : https://my-domain/docs

How do I generate my documentation so that I get an index.html referring the static files to 'docs/css/my-style.css'
instead of '_static/css/style.css'.

I don't want to tell my nginx to redirect the urls that target https://my-domain/_static to https://my-domain/docs/_static.

Also I don't understand how the github extension page can help https://www.sphinx-doc.org/en/master/usage/extensions/githubpages.html#module-sphinx.ext.githubpages

This is not really my need and it is extremely related to GH pages.

We could provide configuration that allow us to configure the static output directory properly.

Maybe I missed something ;)

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by reviewing Sphinx's static-file output handling and its configuration for the _static directory, then compare the githubpages extension mentioned in the issue. Define how a configurable output directory would affect generated HTML, images, JavaScript, and CSS; the work is done when documentation under a /docs prefix references the configured paths without server redirects.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
documentation
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Needs clarification
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.