Question for People Familiar with Sphinx Documentation (lemmy.world)

submitted 2 weeks ago by AstroLightz@lemmy.world to c/python@programming.dev

3 comments fedilink hide all child comments

So, I'm making documentation for my project using Sphinx with hatch/hatchling. I'm currently using the sphinx-rtd-theme as my theme. I already make a quickstart page for my project, but the src directory page is included in the sidebar. I would like to rename it to "Source Files", but when changing the header in my modules.rst file, it gets reset each time I build.

The main extensions I'm using for Sphinx are 'sphinx.ext.todo', 'sphinx.ext.viewcode', and 'sphinx.ext.autodoc'.

For context, my project structure looks something like this:

my_project/
| ---- requirements.txt
| ---- README.md
| ---- src/
| -------- my_project_module/
| -------------- __init__.py
| -------------- foo.py
| -------------- bar.py
| -------- docs/
| -------------- requirements.txt
| -------------- requirements.in
| -------------- conf.py
| -------------- modules.rst
| -------------- index.rst
| -------------- quickstart.rst
| -------------- my_project_module.rst
| -------------- _static/
| ------------------ some_img.png

Is there a way to change the display name of my src directory without renaming the actual directory in my project?

Also, is there a way to reorder the list so my quickstart guide shows up above the source page?

you are viewing a single comment's thread
view the rest of the comments

[-] logging_strict@programming.dev 1 points 2 weeks ago* (last edited 2 weeks ago)

i wrote sphinx-external-toc-strict, which is a safer sphinx-external-toc. So i'm competent in Sphinx docs.

docs/ folder

Follow /u/GrumpyBike1020 advise and move the docs/ out of src/ and into the project base folder.

venv

Create two venv .doc/.venv and .venv. Assuming you're using pyenv, create .doc/.python-version and .venv/.python-version and .tox/.python-version. Add these to your .gitignore.

requirements management

Your requirements management is overly simplistic. Do yourself a favor and use wreck to manage multiple venv requirements.

pyproject.toml configuration

Copy tox-req.ini into your project base folder.

in docs/

reference docs/conf.py

add this docs/Makefile modify as needed.

Here is an example docs/_toc.yml modify for your needs.

add this rtd config and be aware of the Python version must match Python version in tox.ini. You will forget this, it'll bite you in the ass, then you'll learn this lesson good and hard. Just come to terms that you will make this mistake.

You are gonna have to get really good at using intersphinx inventories. The docs/Makefile will lessen the learning curve.

The front page of your site is docs/index.rst, Create folder: docs/code. This is the root folder of your in-code documentation.

I would like to rename it to “Source Files”

No you don't. No table of contents in the history of time had a root named, Source files. In the TOC, you'll have a bunch of articles and a code/ folder.

When you have questions, i'm always paying attention to this community. Just post a question will be sure to see it. Don't forget to provide your projects github repo url. Explain your issue and ask me to fix it. I'll create an GH issue with the proposed change. You have to give me the go ahead before i'll do any coding leading to a PR. I need your assurances that the change meets your approval before starting.