sphinx-doc / sphinx-doc/sphinx

add `.. file::` directive

Open
#8,252 2 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

type:enhancement
Dominant language
Python
Stars
8k
Forks
2.6k
PR merge metrics
No merged PRs in 30d

Description

Is your feature request related to a problem? Please describe.
Like environment variables, I want to have a specific page in my user manual to explain all files relevant to my application (like you usually have a FILES section in a manpage).

Describe the solution you'd like
.. file:: would make sense, similar to .. envvar::. Then when you do

:file:`myfile`

, if there is a .. file:: myfile entry somewhere, it will link to it.

Describe alternatives you've considered
There's probably a way to implement a custom directive, but since we already have program, option and envvar, I think it would make sense to have file too.

Additional context
See our environment variables page for example: https://manual.zrythm.org/en/appendix/environment.html

In the next page, I want to have something similar for "Files and Directories"

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 examining Sphinx's existing envvar, program, and option directive and role implementations, along with the linked environment-variables page. Define the file directive and :file: role to mirror their behavior, then verify that a documented file entry resolves to a link from :file:myfile.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
documentation
Issue type
Feature
Difficulty
4/5
Estimated time
3-5 days
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
48/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.