Update readme with Usage instructions #39

Sheila-nk · 2023-03-02T12:40:18Z

refined the project's description
added a usage section with installation and import instructions
added an integration example using the DockerSpawner draft PR

Closes #37

Sheila-nk · 2023-03-02T13:16:49Z

The ReadTheDocs build is failing and I think it is because of the pydata-sphinx-theme v0.13.0 which was released a couple of days ago. There is this note on the pypi page that it might not be compatible with the most recent version of Sphinx which I believe we are using according to the build logs.

Note This theme may not work with the latest major versions of Sphinx, especially if they have only recently been released. Please give us a few months of time to work out any bugs and changes when new releases are made.

Do you think we should pin the pydata-sphinx-theme extension to the lower version before the compatibility issue is sorted?

manics · 2023-03-02T13:59:46Z

Since RTD is a "production" deployment of our docs we could pin all deps and let dependabot bump them?

If you want we could also switch to jupyterhub-sphinx-theme jupyterhub/team-compass#524

Sheila-nk · 2023-03-03T09:00:02Z

@manics Thanks for the suggestion. I have looked over the jupyterhub-sphinx-theme and the JupyterHub Python Repo Template Draft PR using it. I like it and I think we should go ahead and make the switch too.
So I will work on:

making a draft PR using the jupyterhub-sphinx-theme
creating a dependabot.yml configuration file to update dependencies

Sheila-nk · 2023-03-20T08:02:11Z

Ping @GeorgianaElena could you please help review this PR?

README.md

manics · 2023-03-20T19:10:15Z

README.md

+[![Latest PyPI version](https://img.shields.io/pypi/v/pytest-jupyterhub?logo=pypi)](https://pypi.python.org/pypi/pytest-jupyterhub)
+[![Documentation status](https://img.shields.io/readthedocs/pytest-jupyterhub?logo=read-the-docs)](https://pytest-jupyterhub.readthedocs.io/en/latest/?badge=latest)
+[![GitHub Workflow Status - Test](https://img.shields.io/github/workflow/status/jupyterhub/pytest-jupyterhub/Test?logo=github&label=tests)](https://github.com/jupyterhub/pytest-jupyterhub/actions)
+[![Test coverage of code](https://codecov.io/gh/jupyterhub/pytest-jupyterhub/branch/main/graph/badge.svg)](https://codecov.io/gh/jupyterhub/pytest-jupyterhub)


Is https://codecov.io/gh/jupyterhub/pytest-jupyterhub meant to be public?

I am not sure I understand what you mean by 'public', but we have not set up the project on codecov yet. I don't think I have the relevant permissions for that. I can delete this badge for now until that is done.

codecov doesn't look to be setup for this repo yet. I believe it makes sense to not have a badge for it.
Also, @Sheila-nk, can you please open up an issue about enabling codecov for this repo?

manics · 2023-03-20T19:17:23Z

README.md

@@ -17,8 +29,63 @@ For more information on Fixtures, check out this [pytest documentation](https://
 A **Mock** is an object that simulates the behavior of another object such as a class or function. They are used to simulate the behavior of real objects for testing purposes.
 For more information on Mocks, check out this [unittest documentation](https://docs.python.org/3/library/unittest.mock.html) on the mock module.

-**Example:**
+### Example


Is it worth deleting this "Example" section? It's a bit confusing having two "Example" sections in the README, and this one goes into a lot of technical detail. The usage example you've added below seems much more relevant and helpful to readers.

Okay, I agree. I will remove this example section.

manics · 2023-03-20T19:21:27Z

README.md

+
+# [Reusable JupyterHub Pytest Plugin](https://github.com/jupyterhub/pytest-jupyterhub)
+
+[![Latest PyPI version](https://img.shields.io/pypi/v/pytest-jupyterhub?logo=pypi)](https://pypi.python.org/pypi/pytest-jupyterhub)


If we're adding a pypi badge with link we should push something there to claim ownership, even if it's a placeholder package.

@GeorgianaElena suggested we make an alpha release of this project. We can hold on adding the pypi badge until that is done.

@Sheila-nk, can you please open an issue about making a release and adding the corresponding docs, GitHub workflow, badge, etc, to make sure we keep track of it? Thank you ❤️

Here it is: #45
You can add any steps I have missed or remove any unnecessary ones.

GeorgianaElena · 2023-03-23T09:15:57Z

README.md


-Each of these hub components and the hub itself define their own testing infrastructure, building everything from the ground up using the **pytest** framework. And some of this complex work is either repetitive across JupyterHub sub-projects, or under-specified for some of them. This has sparked a need to abstract these common parts into a separate testing framework.
+Each of these hub components and the hub itself define their own testing infrastructure, building everything from the ground up using the [**pytest**](https://docs.pytest.org/en/7.2.x/) framework. And some of this complex work is either repetitive across JupyterHub sub-projects, or under-specified for some of them. This has sparked a need to abstract these common parts into a separate testing framework.


Let's link to the pytest stable or latest docs, instead of a certain version, as it might not always be the version used by this project.

GeorgianaElena · 2023-04-03T16:29:07Z

README.md

+
+To use the **JupyterHub Pytest Plugin**, you will first need to install it using pip by either:
+
+- installing it locally


I believe it's worth leaving a note here about the fact that we're instructing to install the package from GitHub because the package was not yet released on PyPI. And then change the install instruction once that's done. Also, adding this to a todo list, somewhere in an issue to not forget, will be also a good idea.

GeorgianaElena · 2023-04-03T16:30:21Z

README.md

+
+- installing it locally
+ ```bash
+ pip install --upgrade pip


Let's remove this step, as upgrading pip is not a requirement of the project.

GeorgianaElena · 2023-04-03T16:32:17Z

README.md

+- adding it to the `requirements.txt` file of your project:
+
+ ```python
+ # in requirements.txt
+ git+https://github.com/jupyterhub/pytest-jupyterhub.git@main
+ ```


This is subject to how each project is managing their dependencies, and it's hard and not recommended to cover all cases, so let's remove and leave it to each project to define.

GeorgianaElena · 2023-04-03T16:36:49Z

README.md

+ ```bash
+ pip install --upgrade pip
+ pip install -r requirements.txt
+ ```


When installing a package with pip install git+https://github.com/jupyterhub/pytest-jupyterhub.git@main, its dependencies get installed also.

Plus, we're defining the pytest-jupyterhub's deps in pyproject.toml and don't actually have a requirements.txt file in this repo, right?

Oh yes! That is my mistake. All dependencies are defined in pyproject.toml. No requirements.txt file for this project, except for the docs.

GeorgianaElena · 2023-04-03T16:40:33Z

README.md

+## Usage
+
+To use a specific fixture or mock, import it from its module in the `pytest_jupyterhub` package:
+
+```python
+from pytest_jupyterhub.jupyterhub_spawners import hub_app
+```


The pytest docs describe differently how to use a plugin in a test suite: https://docs.pytest.org/en/7.1.x/how-to/writing_plugins.html#requiring-loading-plugins-in-a-test-module-or-conftest-file

Is there a reason why we're taking a different approach here and importing the fixtures same like we'd do from a regular Python package?

Hmm, true. I might need to change the DockerSpawner draft PR as well since I imported it instead of loading the plugin. Thank you for catching this.

for more information, see https://pre-commit.ci

Co-authored-by: Simon Li <[email protected]>

Sheila-nk · 2023-04-10T08:31:15Z

@GeorgianaElena I have worked on the recommended changes and added a contributing section to this README. Please review the changes and let me know if they are ready for merging.

consideRatio

This looks great to me! I made two code suggestions that I think makes sense.

README.md

consideRatio · 2023-04-13T10:48:46Z

@Sheila-nk btw amazing README.md file, I love it! It does a perfect job introducing a reader I think - it doesn't assume too much knowledge ahead of time and onboards the reader, and it doesn't try to explain too much either. Perfectly balanced in my mind!

Co-authored-by: Erik Sundell <[email protected]>

Sheila-nk · 2023-04-13T12:49:55Z

@Sheila-nk btw amazing README.md file, I love it! It does a perfect job introducing a reader I think - it doesn't assume too much knowledge ahead of time and onboards the reader, and it doesn't try to explain too much either. Perfectly balanced in my mind!

Thank you @consideRatio for your kind words and review ❤️

Sheila-nk added documentation Improvements or additions to documentation and removed documentation Improvements or additions to documentation labels Mar 3, 2023

Sheila-nk marked this pull request as draft March 8, 2023 09:29

Sheila-nk marked this pull request as ready for review March 16, 2023 08:29

manics reviewed Mar 20, 2023

View reviewed changes

README.md Outdated Show resolved Hide resolved

manics reviewed Mar 20, 2023

View reviewed changes

Sheila-nk requested a review from manics March 23, 2023 08:03

GeorgianaElena reviewed Mar 23, 2023

View reviewed changes

Sheila-nk mentioned this pull request Mar 24, 2023

Initial release of pytest-jupyterhub #45

Closed

5 tasks

Sheila-nk requested a review from GeorgianaElena March 27, 2023 09:30

GeorgianaElena reviewed Apr 3, 2023

View reviewed changes

Sheila-nk requested a review from GeorgianaElena April 5, 2023 10:15

Sheila-nk and others added 8 commits April 10, 2023 11:06

add usage section

43bcc64

remove directives syntax

058d23c

[pre-commit.ci] auto fixes from pre-commit.com hooks

221c380

for more information, see https://pre-commit.ci

provide alternative installation instructions

4a4a895

add workflow status badges

c583475

use relevant link for workflow status badge

ddff3e8

Co-authored-by: Simon Li <[email protected]>

remove example section

efa2a23

remove unavailable badges

27a0102

Sheila-nk added 3 commits April 10, 2023 11:06

link to docs of pytest's stable version

40eb45c

change usage and installation instructions

97e7e02

add contributing instructions

9f8fe41

Sheila-nk force-pushed the update-readme branch from 3f66035 to 9f8fe41 Compare April 10, 2023 08:26

Sheila-nk added the documentation Improvements or additions to documentation label Apr 11, 2023

consideRatio approved these changes Apr 13, 2023

View reviewed changes

README.md Outdated Show resolved Hide resolved

README.md Outdated Show resolved Hide resolved

Sheila-nk and others added 2 commits April 13, 2023 15:42

use img.shields.io badge

b7280fc

Co-authored-by: Erik Sundell <[email protected]>

update install instructions

b13915b

Co-authored-by: Erik Sundell <[email protected]>

consideRatio merged commit 264a2aa into jupyterhub:main Apr 13, 2023

Sheila-nk mentioned this pull request Apr 13, 2023

Update readme install instructions #51

Closed

Sheila-nk deleted the update-readme branch April 13, 2023 12:59

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Update readme with Usage instructions #39

Update readme with Usage instructions #39

Sheila-nk commented Mar 2, 2023 •

edited

Loading

Sheila-nk commented Mar 2, 2023

manics commented Mar 2, 2023

Sheila-nk commented Mar 3, 2023 •

edited

Loading

Sheila-nk commented Mar 20, 2023

manics Mar 20, 2023

Sheila-nk Mar 21, 2023 •

edited

Loading

GeorgianaElena Mar 23, 2023

manics Mar 20, 2023 •

edited

Loading

Sheila-nk Mar 21, 2023

manics Mar 20, 2023

Sheila-nk Mar 21, 2023

GeorgianaElena Mar 23, 2023

Sheila-nk Mar 23, 2023

GeorgianaElena Mar 23, 2023

GeorgianaElena Apr 3, 2023

GeorgianaElena Apr 3, 2023

GeorgianaElena Apr 3, 2023

GeorgianaElena Apr 3, 2023

Sheila-nk Apr 4, 2023

GeorgianaElena Apr 3, 2023

Sheila-nk Apr 4, 2023

Sheila-nk commented Apr 10, 2023

consideRatio left a comment

consideRatio commented Apr 13, 2023

Sheila-nk commented Apr 13, 2023


		# [Reusable JupyterHub Pytest Plugin](https://github.com/jupyterhub/pytest-jupyterhub)

		[![Latest PyPI version](https://img.shields.io/pypi/v/pytest-jupyterhub?logo=pypi)](https://pypi.python.org/pypi/pytest-jupyterhub)


		Each of these hub components and the hub itself define their own testing infrastructure, building everything from the ground up using the pytest framework. And some of this complex work is either repetitive across JupyterHub sub-projects, or under-specified for some of them. This has sparked a need to abstract these common parts into a separate testing framework.
		Each of these hub components and the hub itself define their own testing infrastructure, building everything from the ground up using the [pytest](https://docs.pytest.org/en/7.2.x/) framework. And some of this complex work is either repetitive across JupyterHub sub-projects, or under-specified for some of them. This has sparked a need to abstract these common parts into a separate testing framework.


		To use the JupyterHub Pytest Plugin, you will first need to install it using pip by either:

		- installing it locally

Update readme with Usage instructions #39

Update readme with Usage instructions #39

Conversation

Sheila-nk commented Mar 2, 2023 • edited Loading

Sheila-nk commented Mar 2, 2023

manics commented Mar 2, 2023

Sheila-nk commented Mar 3, 2023 • edited Loading

Sheila-nk commented Mar 20, 2023

Choose a reason for hiding this comment

Sheila-nk Mar 21, 2023 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

manics Mar 20, 2023 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Sheila-nk commented Apr 10, 2023

consideRatio left a comment

Choose a reason for hiding this comment

consideRatio commented Apr 13, 2023

Sheila-nk commented Apr 13, 2023

Sheila-nk commented Mar 2, 2023 •

edited

Loading

Sheila-nk commented Mar 3, 2023 •

edited

Loading

Sheila-nk Mar 21, 2023 •

edited

Loading

manics Mar 20, 2023 •

edited

Loading