Sphinx: How to change theme output directory from `_static` to `static`

[weaming]

How to change theme output directory from _static to static

I can't find any setting in conf.py or other file.

[weaming]

@shimizukawa help me

[shimizukawa]

@weaming you can't. However, https://pypi.python.org/pypi/sphinxtogithub will helps you to output into static directory.

Internally, Sphinx implements '_static' on several places: https://github.com/sphinx-doc/sphinx/blob/master/sphinx/builders/html.py

[weaming]

@shimizukawa Is this mean adding a blank file named .nojekyll to the repo's root directory works for this situation?

I think change this name into one argument in conf.py would be better.

[shimizukawa]

sphinxtogithub is a workaround for github pages that ignores underscore prefixed directories.

I think change this name into one argument in conf.py would be better.

Agreed. I filed #2203 that is a enhancement proposal for sphinx conf.py.

[weaming]

@shimizukawa Adding blank file named .nojekyll in root directory works for me.

[shimizukawa]

@weaming If you issue is "want to use github pages", Yes, .nojekyll is a better way than sphinxtogithub extension.
Now I close this thicket.

[WarrenWeckesser]

Could you make the name of _static configurable? This is a real nuisance.

[tk0miya]

@WarrenWeckesser Please let me know your problem in detail. We need to know how it is useful before implementing.

[WarrenWeckesser]

Takeshi,

The tone of my terse comment above reflects the frustration I was feeling when I wrote it. Not frustration with sphinx per se, but with the unfortunate interaction of sphinx and github pages that meant I spent far too many hours trying to figure out why my documentation on github pages was not picking up the style files and javascript in the _static directory. Eventually I stumbled across the fact that github pages ignore data in directories that begin with '_'. "No problem", I thought, "I'll just change that directory in the sphinx configuration file." After poking around a bit, I eventually landed here, and found that I can't change that directory through sphinx configuration. But I also learned about adding the '.nojekyll' file to the root directory in my github pages repository. So I did that, and the documentation that I was working on now renders correctly.

I don't yet know if using '.nojekyll' is a good long-term solution, because I don't know what other implications that has on a github pages site. That documentation I was just working on is completely generated through a mixture of Python scripts and sphinx. But I've been experimenting with a blog that would be implemented with jekyll, and I don't know if adding '.nojekyll' will interfere with that. If it turns out that it does, I can always remove '.nojekyll', and post-process my sphinx-generated documentation with a global search-and-replace that changes '_static' to 'static' in the generated web pages.

So, leave this issue closed. I'll be back if, after gaining more experience with github pages, I have more concrete and useful suggestions. :)

[tk0miya]

Thank you for explanation. I understand your situation. For GitHub Pages, we've provided githubpages extension: https://www.sphinx-doc.org/en/master/usage/extensions/githubpages.html. It creates .nojekyll and other files automatically. And it will follow the rule of GitHub Pages. So I recommend you to use it on your project. Then it will be help you.

About changing the _static directory, I'm okay to add a configuration if it is really needed. But, at same time, I'd not like to add it without discussion. Because it will make Sphinx more complex and hard to maintain it. IMO, to keep sphinx maintainable, it would be better to add a configuration if really needed.

Thank you for comment. Please let me know if .nojykell file (or githubpages extension) not working.

[teachamantofish]

Is this a useful suggestion?: Real case example: I have one doc version in English. It's translated into 18 other langs. I don't want 19 image and 19 static dirs. A single directory all those lang version reference is far better. So I have a batch file that copies the static and image dirs one level up and then a script changes the static path from _static to ../static. Same for images. That way all 19 doc versions can point to a single directory that's not a subdir of just one language. It would be far easier to avoid the copying and regex and just set the static and image paths in conf.py.

[assombrance]

Hi, I have a project where I have a mixture of regular github-pages and sphinx documentation. I will end up by splitting both into two projects, but I really don't like this solution.
Because of this, it would indeed be great to have a jekyll compatible mode (or github compatible).