Add: dependency page to guide

[lwasser]

This is a file generated via discussion in our community slack with a lot of feedback from folks there. all review is welcome.

---

• To see the specific tasks where the Asana app for GitHub is being used, see below:
  • https://app.asana.com/0/0/1206105000277649

[lwasser]

@all-contributors please add @Zeitsperre for code, review

thanks for the input on this trevor!

[allcontributors]

@lwasser

I've put up a pull request to add @Zeitsperre! 🎉

I couldn't determine any contributions to add, did you specify any contributions?
Please make sure to use valid contribution names.

[sneakers-the-rat]

I feel bad because I pick on the ToC literally every time, but i rely on them to skim and read on the internet! in this case making it hard for me to tell which section goes with which (eg. is the "If you are using a front-end build tool like PDM, Hatch, or Poetry" section a top-level section as a global alternative to everything above, or it just a note about the preceding readthedocs section?

Currently toc is:

Declaring Development Dependencies - Python Packaging
|- How to declare documentation, test, and other dependencies
|- Direct project dependencies
|- Development dependencies
|- How to declare development dependencies
|- How to install dependencies from your pyproject.toml
|  |- Combining sets of dependencies
|- Where does conda fit in ?
|- Read the Docs & project dependencies
|- If you are using a front-end build tool like PDM, Hatch or Poetry

But without changing the content the ToC could be

Dependencies
|- Declaring Dependencies
|  |- Required Dependencies
|  |- Optional Dependencies
|  |- Combining Optional Dependencies
|- Conda Environments
|- CI Environments
|  |- Read The Docs

which is very skimmable, groups similar content together, and gives us clear points of expansion in the future should someone like to contribute eg. guides on using different tools like PDM/Hatch/etc. (change "Conda Environments" into "Other Formats" and then Conda becomes one of several other examples) or other CI environments.

Just an example, i get how this is not obvious while writing. You mentioned previously wanting to have big long titles for SEO, but i think SEO mostly cares about the <title> metadata element not the actual displayed title on the page, so since sphinexect-opengraph is already being used here, one can just set that metadata separately, eg.

:og:title: Big Long SEO Title To Appear In Search Engine Results

# More Manageable Title

For In-page and ToC display

Or I think that might be {og}{title}Title` in myst-md. not sure.

[sneakers-the-rat]

Lovely! Thanks as always for your work Leah :)

Good with p much all of this. Most of my comments are for clarity, tried to keep them useful and not nitpicky.

The main thing that's missing here is a discussion of version specifications. That's the thing i spend the most time fiddling with by far, and so I think we need

• Why you specify them
• How to specify them
• When you use different specifiers

as a baseline. Couple paras tops, doesn't need to be exhaustive, and i can draft something for this.

I also think it would be lovely to add tabbed examples for each of the major package managers here so ppl can stick with default complexity or also check out the other equivalent tabs if they're curious/for their reference if they end up on different tools. i've already made an example like that in a previous PR: #104 (comment) and would be happy to put it in the same tab groups format as setuptools uses here: https://setuptools.pypa.io/en/latest/userguide/dependency_management.html

Thanks again again!

[sneakers-the-rat]

right, ya, need context of what conda does differently to know why this would be more reliable/reproducible

[lwasser]

ok got it. i think the text your suggest above is a great segway and will tighten up this section.

[lwasser]

so looking at this further i'm not sure if we want the conda info above here. in my mind, this section was more for contributors who might use conda environments and are less aware of venv, etc. i'll keep this open but it feels a like a bit too much for this specific page.

[sneakers-the-rat]

ya i think you're right (in general I prefer more, smaller, focused pages in a navigable hierarchy than everything in a few, very large pages in a list). Maybe it would be good at the bottom just to say "all this is for python dependencies only, we will cover system/non-python dependencies elsewhere, but hint hint this is what conda is for"

[lwasser]

that is a great idea. i do think it's important information!!

[lwasser]

NOTE: from @ucodery

I just did some testing on shells I'm less familiar with. fish and ksh are fine with no quotes or single or double. csh needs quotes, single or double. (all UNIX). cmd and PowerShell both can do no quotes or double, but not single.
So indeed, ".[something]" seems like the most universal example

[lwasser]

I feel bad because I pick on the ToC literally every time, but i rely on them to skim and read on the internet! in this case making it hard for me to tell which section goes with which (eg. is the "If you are using a front-end build tool like PDM, Hatch, or Poetry" section a top-level section as a global alternative to everything above, or it just a note about the preceding readthedocs section?

Currently toc is:

Declaring Development Dependencies - Python Packaging
|- How to declare documentation, test, and other dependencies
|- Direct project dependencies
|- Development dependencies
|- How to declare development dependencies
|- How to install dependencies from your pyproject.toml
|  |- Combining sets of dependencies
|- Where does conda fit in ?
|- Read the Docs & project dependencies
|- If you are using a front-end build tool like PDM, Hatch or Poetry

But without changing the content the ToC could be

Dependencies
|- Declaring Dependencies
|  |- Required Dependencies
|  |- Optional Dependencies
|  |- Combining Optional Dependencies
|- Conda Environments
|- CI Environments
|  |- Read The Docs

which is very skimmable, groups similar content together, and gives us clear points of expansion in the future should someone like to contribute eg. guides on using different tools like PDM/Hatch/etc. (change "Conda Environments" into "Other Formats" and then Conda becomes one of several other examples) or other CI environments.

Just an example, i get how this is not obvious while writing. You mentioned previously wanting to have big long titles for SEO, but i think SEO mostly cares about the <title> metadata element not the actual displayed title on the page, so since sphinexect-opengraph is already being used here, one can just set that metadata separately, eg.

:og:title: Big Long SEO Title To Appear In Search Engine Results

# More Manageable Title

For In-page and ToC display

Or I think that might be {og}{title}Title` in myst-md. not sure.

Hey @sneakers-the-rat i love how you think about structure of a page. it's important. i've restructured - it's not exactly what you suggested but very close! to me RTD is not just CI it's a publication platform. so i just adjusted the wording a bit but followed your suggestions!

i do have questions about this part --

> :og:title: Big Long SEO Title To Appear In Search Engine Results

i keep reading that you can have front matter in sphinx but i haven't seen a good example of how you add that in myst-md. i've looked.

if someone could help me understand that (i see this page here for instance but don't know how to translate that to the top of a .md file) -- id' greatly appreciate it. maybe i can ask on slack even?

[lwasser]

The main thing that's missing here is a discussion of version specifications. That's the thing i spend the most time fiddling with by far, and so I think we need

• Why you specify them
• How to specify them
• When you use different specifiers

as a baseline. Couple paras tops, doesn't need to be exhaustive, and i can draft something for this.

ok this is the one item i haven't addressed yet
@sneakers-the-rat if you are open to drafting this text that would be wonderful. you could either:

• add it as a big inline comment to this pr which would directly add a commit.
• submit a pr to my fork
• add it as a pr to this repo AFTER we merge next week.

i have no preference so let's do what is easiest / most convenient for you! thank you!!!

ps - i've just pushed all of my changes up to all of the other comments including a restructure that you suggested. i think we're getting close! 🚀

[ucodery]

NOTE: from @ucodery

I just did some testing on shells I'm less familiar with. fish and ksh are fine with no quotes or single or double. csh needs quotes, single or double. (all UNIX). cmd and PowerShell both can do no quotes or double, but not single. So indeed, ".[something]" seems like the most universal example

This seemed a bit non-sequitur in this thread. I was arguing that pip install examples that will work for the most users need double quotes around the argument (the square braces of extras specifically can cause issues) because of some testing I did.

SHELL	no quote	single quote	double quote
bash	✅	✅	✅
zsh	❌	✅	✅
fish	✅	✅	✅
ksh	✅	✅	✅
csh	❌	✅	✅
cmd	✅	❌	✅
PowerShell	✅	❌	✅

[ucodery]

I think this is now covered by the earlier introduction.

[ucodery]

It shouldn't be. The example you gave used pip to install the readthedocs dependencies. pip can install any PDM, Hatch, etc project, including any optional dependencies they specify. Even if specified in a metadata format other than project.optional-dependencies. (but not, I suppose, if they are specified as a type of environment and not an optional)

[lwasser]

you are right. i was confusing things, @ucodery i think what i noticed is that PDM, hatch poetry add dependencies to the pyproject.toml differently (hatch may not add them yet actually). but installation (with pip) could be similar. this is what i just don't know. poetry has it's own tables i think - can pip still install from them?

but i think a bigger takeaway for me here potentially is that we don't need to confuse our readers with the nuances of all of these tools here - they can read the docs. and we can link to the RTD docs for builds that use other tools such as poetry if users want to use those tools. hopefully the changes i've made make this all more clear and address your comments!!

[sneakers-the-rat]

Copying reply from slack just for the sake of having it public in the issue:

re: this comment - #106 (comment)

Put this at the top of the file:

```{eval-rst}
:og:title: my fancy title
```

it turns out they aren’t actually sphinx roles, but that extension’s parser looks for strings matching that pattern that sorta looks like a role, but if myst gets to it first then it misses them, so you need to wrap in the eval-rst block

without the extension you would use this https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#html-meta

```{meta}
:og:title: My title
:description: whatever other meta tags you want
```

gets you

<meta name="og:title" content="My title">
<meta name="description" content="whatever other meta tags you want>

[sneakers-the-rat]

ok this is the one item i haven't addressed yet @sneakers-the-rat if you are open to drafting this text that would be wonderful. you could either:

* add it as a big inline comment to this pr which would directly add a commit.

* submit a pr to my fork

* add it as a pr to this repo AFTER we merge next week.

Maybe for now just put in a section "Version Specifiers" with a "TODO" admonition and I can do a PR after we merge this :) don't want to hold things up.

[lwasser]

@sneakers-the-rat (i always chuckle a bit because your username is so awesome).

i added an intro at the top of the page titled "What are dependencies". that is like guidebook / tutorial 101 that i forgot! but i left a TODO admonition for you to work on the specifiers related to adding deps!!

i THINK i captured everyone's comments here - but if you re-read the page and i missed something please do call it out. when you get above 100+ comments in a review - github starts hiding things and it's really easy to miss comments. but hopefully i caught them all. really great work everyone catching issues / typos / mistakes etc! thank you.

[jhkennedy]

Looks great!

[lwasser]

@all-contributors please add @jhkennedy for code, review

[allcontributors]

@lwasser

I've put up a pull request to add @jhkennedy! 🎉

[mknorps]

Looks great and will help a lot of people ❤️ @

[lwasser]

@all-contributors please add @mknorps for code, review

[allcontributors]

@lwasser

I've put up a pull request to add @mknorps! 🎉

[lwasser]

ok y'all!! i'm thrilled! i believe i've incorporated EVERYONE's feedback both from slack (where we discussed graphics) and here. i feel good about merging this for now. we have had extensive review and discussion and have landed i think on some good content.

Given this is a living community guidebook, we can always adjust / fix / make better through pr's.

I opened an issue (#134) around the shell discussion which actually was fairly extensive. I think will be a user pain point for some but it's out of scope for this specific PR so let's revisit it!

All checks are now passing. i am going to merge this!

[sneakers-the-rat]

Nice work every1 :)

[ucodery]

II realize this already merged so I just left some copy edits 😆

[ucodery]

Suggested change

	Optional dependencies dependencies can be optionally installed by users
	Optional dependencies can be chosen to be installed by users

[ucodery]

Suggested change

	1. **Development dependencies**: These are dependencies that are required to support development of your package. They include tools to run tests such as `pytest`, linters (like `flake8` and `ruff`) and code formatters such as `black` and even automation tools such as `nox` or `tox` that run tasks.
	1. **Development dependencies**: These are dependencies that are required to support development of your package. They include tools to run tests such as `pytest`, linters such as `flake8` and `ruff`, and code formatters such as `black` and even automation tools such as `nox` or `tox` that run tasks.
	2. ```

[ucodery]

Suggested change

	You can think about dependencies as being either optional or required. If they are required, they will be listed in the `[dependency] =` table of your `pyproject.toml` file. If they are optional, they will be listed in the `[optional.dependencies]` table of your `pyproject.toml`.
	You can think about dependencies as being either optional or required. If they are required, they will be listed in the `dependency` array of your `pyproject.toml` file. If they are optional, they will be listed in the `[optional.dependencies]` table of your `pyproject.toml`.

[ucodery]

Suggested change

	as **core dependencies** as they are needed in order to run your package. You should place your core or required dependencies in the `[dependency]=` table of your `pyproject.toml` file.
	as **core dependencies** as they are needed in order to run your package. You should place your core or required dependencies in the `dependency` array of your `pyproject.toml` file.

[ucodery]

As a future edit note, dependencies in pyproject.toml are referred to as: a table, an array, and a section just in this guide. And it is designated as both dependencies and [dependencies] (and [dependencies]=). By the book, the dependencies variable of the project table is always an array.

[ucodery]

Suggested change

	`[dependencies]` section. This minimizes the number of
	`dependencies` array. This minimizes the number of

[ucodery]

Suggested change

	When a user installs your package locally using python -m pip install your-package only your package and it's core dependencies get installed. When they install your package `[tests]` pip will install both your package and its core dependencies plus any of the dependencies listed within the tests array of your `[optional.dependencies]` table.
	When a user installs your package locally using `python -m pip install your-package` only your package and it's core dependencies get installed. When they install `your-package[tests]` pip will install both your package and its core dependencies plus any of the dependencies listed within the tests array of your `[optional.dependencies]` table.

[ucodery]

Suggested change

	Within those 2 groups, there are three use cases that you can think about. 1. Core dependencies are **required** for a user to use your package. 2. Development dependencies are optional and only needed if someone wants to work on your package locally. 3. Finally feature dependencies are optional and add additional functionality to your package. Not all packages will have feature dependencies.
	Within those two groups, there are three use cases that you can think about. 1. Core dependencies are **required** for a user to use your package. 2. Development dependencies are optional and only needed if someone wants to work on your package locally. 3. Finally feature dependencies are optional and add additional functionality to your package. Not all packages will have feature dependencies.