Fix Poetry dependencies with sphinx-tags

Fix Poetry dependencies with sphing-tags
epics-docs · Sep 7, 2023 · c116637 · c116637
2 parents 0fb5d34 + 0840717
commit c116637
Show file tree

Hide file tree

Showing 6 changed files with 247 additions and 9 deletions.
diff --git a/.gitignore b/.gitignore
@@ -1,4 +1,5 @@
 _build/
+_tags/
 .DS_Store
 *.autosave
 QtC-*
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -86,7 +86,7 @@ using [sphinx-tags] extension.
 
 There are `beginner`, `user`, `developer`, `advanced` and `all` roles.
 
-* `beginner` - articles for those who don't know the EPICS and want to familarize with it. 
+* `beginner` - articles for those who don't know the EPICS and want to familiarize with it. 
 That should be mostly articles about
 installation and basic concepts.
 
@@ -95,7 +95,7 @@ mostly with client applications
 
 * `developer` - articles for those who develop IOCs, extensions or drivers 
 
-* `advanced` -articles for those who want to understand advanced topics inlcuding build system, specifications,
+* `advanced` -articles for those who want to understand advanced topics including build system, specifications,
 and details of protocols.
 
 
@@ -113,7 +113,7 @@ Example for `.md`:
 
 ~~~
 ```{tags} tag1, tag2
-```  
+```
 ~~~
 
   [sphinx-tags]: https://sphinx-tags.readthedocs.io/
@@ -276,6 +276,40 @@ If all is well, they will approve the changes and merge them into the main repo.
 After the reviewer has merged the pull request,
 Read the Docs will recompile the page and publish your changes.
 
+## Adding dependencies
+
+When adding a dependency,
+make sure to add them to both Poetry and the requirement files.
+
+For example,
+if you want to add the `sphinx-foo` extension,
+first run:
+
+``` bash
+poetry add sphinx-foo
+```
+
+This command adds that extension to both `pyproject.toml` and `poetry.lock`.
+It also fetches the latest version,
+and pins it in `pyproject.toml`.
+
+To add that dependency to the requirement files,
+take the version pinned in `pyproject.toml`,
+and make sure to pin that same version in the requirements files.
+
+For example,
+if you see in `pyproject.toml`:
+
+``` toml
+sphinx-foo = "^1.1.2"
+```
+
+Then you must add to both `requirements.txt` and `requirements-dev.txt`:
+
+```
+sphinx-foo==1.1.2
+```
+
 ## Reviewing pull requests
 
 From the point of view of a reviewer.

diff --git a/poetry.lock b/poetry.lock
diff --git a/pyproject.toml b/pyproject.toml
@@ -2,7 +2,7 @@
 name = "epics-docs"
 version = "0.1.0"
 description = "EPICS documentation located on https://docs.epics-controls.org/"
-authors = ["Your Name <you@example.com>"]
+authors = ["epics-docs contributors"]
 readme = "README.md"
 packages = [{include = "epics_docs"}]
 
@@ -16,6 +16,8 @@ sphinx-rtd-theme = "^1.3.0"
 sphinx-autobuild = "^2021.3.14"
 sphinx-reredirects = "^0.1.2"
 readthedocs-sphinx-search = "^0.3.1"
+sphinx-tags = "^0.2.1"
+sphinx-design = "^0.5.0"
 
 [build-system]
 requires = ["poetry-core"]

diff --git a/requirements-dev.txt b/requirements-dev.txt
@@ -1,7 +1,7 @@
 sphinx_copybutton
 sphinx-hoverxref
-sphinx-tags
-sphinx-design
+sphinx-tags==0.2.1
+sphinx-design==0.5.0
 myst-parser==2.0.0
 sphinx-rtd-theme==1.3.0
 sphinx==7.2.4

diff --git a/requirements.txt b/requirements.txt
@@ -1,7 +1,7 @@
 sphinx_copybutton
 sphinx-hoverxref
-sphinx-tags
-sphinx-design
+sphinx-tags==0.2.1
+sphinx-design==0.5.0
 myst-parser==2.0.0
 sphinx-rtd-theme==1.3.0
 sphinx==7.2.4