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?

top 3 comments

sorted by: hot top controversial new old

[-] GrumpyBike1020@monero.town 2 points 2 weeks ago

Why is docs a child of src? Also: https://packaging.python.org/en/latest/discussions/src-layout-vs-flat-layout/

[-] 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.

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

Life is too short for ‘sphinx.ext.todo’. It's overrated. Won't have enough hours in the day to hunt within in-code documentation for explanation of things you need to do.

Your todo list should be in ur CHANGES.rst file. Won't be building the docs just to see todo list.

Also the moment you have an idea, you immediately write it into CHANGES.rst. Don't wait even one second. Absolutely immediately or as soon as you get home, first thing! Write your idea first, no reading your other ideas. It'll distract you and might cause you to forget.

Don't even think of making any code changes without writing the idea down first.