Add docs folder by h-chmeruk · Pull Request #21 · pyfar/template-pyfar-package

h-chmeruk · 2026-01-21T10:53:29Z

Which issue(s) are closed by this pull request?

Closes #12

Changes proposed in this pull request:

Added the docs folder with the most important files.
Added additional tests to verify the correct creation and content of the new files.

ahms5 · 2026-02-04T10:00:43Z

template/docs/conf.py.jinja

+    {% if 'matplotlib' in dependencies -%}
+    'matplotlib': ('https://matplotlib.org/stable/', None),{% endif %}
+    {% if 'pyfar' in dependencies -%}
+    'pyfar': ('https://pyfar.readthedocs.io/en/stable/', None),{% endif %}


i think we should add the gallery here as well:

Suggested change

'pyfar': ('https://pyfar.readthedocs.io/en/stable/', None),{% endif %}

'pyfar': ('https://pyfar.readthedocs.io/en/stable/', None),{% endif %}

'gallery': ('https://pyfar-gallery.readthedocs.io/en/latest/', None),

ahms5 · 2026-02-04T10:02:41Z

template/docs/history.rst

@@ -0,0 +1 @@
+.. include:: ../HISTORY.rst


Suggested change

.. include:: ../HISTORY.rst

.. include:: ../HISTORY.rst

better to always put a new line at the end of a file, thats easier for git.

ahms5 · 2026-02-04T10:02:47Z

template/docs/index.rst.jinja

+{{ project_slug }} 
+{% for _ in project_slug %}={% endfor %}
+
+.. include:: header.rst


Suggested change

.. include:: header.rst

.. include:: header.rst

ahms5 · 2026-02-04T10:02:52Z

template/docs/contributing.rst

@@ -0,0 +1 @@
+.. include:: ../CONTRIBUTING.rst


Suggested change

.. include:: ../CONTRIBUTING.rst

.. include:: ../CONTRIBUTING.rst

ahms5 · 2026-02-04T10:03:01Z

template/docs/conf.py.jinja

+
+# set dropdown header at pyfar appearance, so that pyfar is the first item in
+# the dropdown called Packages
+html_theme_options['header_links_before_dropdown'] = n_toctree_pyfar


Suggested change

html_theme_options['header_links_before_dropdown'] = n_toctree_pyfar

html_theme_options['header_links_before_dropdown'] = n_toctree_pyfar

ahms5 · 2026-02-04T10:04:10Z

template/docs/api_reference.rst.jinja

+   modules/{{ project_slug }}
+
+
+.. _examples gallery: https://pyfar-gallery.readthedocs.io/en/latest/examples_gallery.html


Suggested change

.. _examples gallery: https://pyfar-gallery.readthedocs.io/en/latest/examples_gallery.html

.. _examples gallery: https://pyfar-gallery.readthedocs.io/en/latest/examples_gallery.html

ahms5 · 2026-02-04T10:04:16Z

template/docs/Makefile.jinja

+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)


Suggested change

@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

ahms5 · 2026-02-04T10:04:48Z

template/docs/readme.rst

@@ -0,0 +1 @@
+.. mdinclude:: ../README.md


Suggested change

.. mdinclude:: ../README.md

.. mdinclude:: ../README.md

ahms5 · 2026-02-04T10:04:56Z

template/docs/{{ project_slug }}.rst.jinja

+        .. raw:: html
+
+            <i class="fa-solid fa-clock-rotate-left icon-style">
+            </i>


Suggested change

</i>

</i>

tests/test_copier.py

ahms5 · 2026-02-04T10:19:37Z

maybe you can also add the .readthedocs.yml config in this pr

h-chmeruk · 2026-02-05T11:17:52Z

Yeah, I will add the .readthedocs.yml file as soon as we merge/close #35. If we merge it, I plan to use the new python_versions parameter to define the default_python_version for the .readthedocs.yml file.

ahms5

from my point of view ready to merge, we can add the readthedocs conf later

ahms5 · 2026-02-06T14:02:12Z

template/docs/conf.py.jinja

+    'matplotlib': ('https://matplotlib.org/stable/', None),{% endif %}
+    {% if 'pyfar' in dependencies -%}
+    'pyfar': ('https://pyfar.readthedocs.io/en/stable/', None),
+    'gallery': ('https://pyfar-gallery.readthedocs.io/en/latest/', None),{% endif %}


mberz · 2026-02-06T17:20:24Z

@h-chmeruk I noticed that merging the last PR created a couple of conflicts. Could you please fix these?

h-chmeruk force-pushed the add-docs-folder branch from c827c6c to 330aa75 Compare January 28, 2026 10:28

h-chmeruk added the enhancement New feature or request label Jan 28, 2026

h-chmeruk marked this pull request as ready for review January 28, 2026 10:29

h-chmeruk requested a review from ahms5 January 28, 2026 10:29

ahms5 requested changes Feb 4, 2026

View reviewed changes

ahms5 added this to the v0.1.0 milestone Feb 4, 2026

ahms5 added enhancement New feature or request and removed enhancement New feature or request labels Feb 4, 2026

ahms5 assigned h-chmeruk Feb 4, 2026

ahms5 added this to Weekly Planning Feb 6, 2026

github-project-automation bot moved this to Require review in Weekly Planning Feb 6, 2026

ahms5 moved this from Require review to Implementation in progress in Weekly Planning Feb 6, 2026

ahms5 self-requested a review February 6, 2026 13:51

ahms5 approved these changes Feb 6, 2026

View reviewed changes

github-project-automation bot moved this from Implementation in progress to Reviewer Approved in Weekly Planning Feb 6, 2026

ahms5 mentioned this pull request Feb 6, 2026

add .readthedocs.yml config to template #36

Closed

ahms5 requested review from a team and hoyer-a February 6, 2026 14:08

h-chmeruk added 2 commits February 9, 2026 09:49

Added docs folder, adjusted and added tests

8c35bea

Added new lines at the end of the files

7aef990

h-chmeruk force-pushed the add-docs-folder branch from 5ce135f to 7aef990 Compare February 9, 2026 08:51

ahms5 merged commit af66b36 into main Feb 9, 2026
11 checks passed

github-project-automation bot moved this from Reviewer Approved to Done in Weekly Planning Feb 9, 2026

	'pyfar': ('https://pyfar.readthedocs.io/en/stable/', None),{% endif %}
	'pyfar': ('https://pyfar.readthedocs.io/en/stable/', None),{% endif %}
	'gallery': ('https://pyfar-gallery.readthedocs.io/en/latest/', None),

		@@ -0,0 +1 @@
		.. include:: ../HISTORY.rst No newline at end of file

		@@ -0,0 +1 @@
		.. include:: ../CONTRIBUTING.rst No newline at end of file

	.. include:: ../CONTRIBUTING.rst
	.. include:: ../CONTRIBUTING.rst

	html_theme_options['header_links_before_dropdown'] = n_toctree_pyfar
	html_theme_options['header_links_before_dropdown'] = n_toctree_pyfar

		modules/{{ project_slug }}


		.. _examples gallery: https://pyfar-gallery.readthedocs.io/en/latest/examples_gallery.html No newline at end of file

	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

		@@ -0,0 +1 @@
		.. mdinclude:: ../README.md No newline at end of file

Conversation

h-chmeruk commented Jan 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Which issue(s) are closed by this pull request?

Changes proposed in this pull request:

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

ahms5 commented Feb 4, 2026

Uh oh!

h-chmeruk commented Feb 5, 2026

Uh oh!

ahms5 left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mberz commented Feb 6, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

h-chmeruk commented Jan 21, 2026 •

edited

Loading