[GH-ISSUE #1109] Documentation Section Suggestion: “A Quick Tutorial To Get Started” #660

New issue

Closed

opened 2026-02-28 00:00:37 +03:00 by kerem · 2 comments

kerem commented

2026-02-28 00:00:37 +03:00

Owner

Originally created by @christianmckinnon on GitHub (May 18, 2024).
Original GitHub issue: https://github.com/spotipy-dev/spotipy/issues/1109

Feature Request & Issue:
When landing on the documentation page as a prospective contributor, I noticed straightaway that after the welcome message and description, we immediately dive into an example of how to interact with the Spotify API without any explicit context or separation from the above section. For a newcomer to the community, the lack of a transition here might detract from the flow of the docs. My understanding is that by placing these accessible Python code snippets directly beneath the welcome message, we can convey the ease with which a developer can get started using the library. This is unfortunately contrasted by the absence of a subheading that explicitly details what the code is intended to do.

Suggested Action:
I think a quick way to remedy this would be to simply add a new subheading, titled, “A Quick Tutorial To Get Started,” to provide separation from the welcome message, and clarity as to the purpose of the code. Specifically, this new subheading would be added after the sentence:

“Spotipy is a lightweight Python library for the Spotify Web API. With Spotipy you get full access to all of the music data provided by the Spotify platform.”

The intention here is to improve the user-friendliness and clarity of the documentation. By directly defining the purpose of the relevant code snippets, developers can more immediately choose to engage in reading the content, or skip to a different subsection that is more related to the task they are trying to achieve.

Alternatives:
I am open to rewording the Section title based on suggestions from the community.

Additional Context: Proposed Solution & Pull Request:
The proposed update would take place after line 9 in the “index.rst” file of the “docs” folder (as seen below). To retain formatting consistency with the remainder of the document, I would suggest including blank spaces on lines 10 and 13, with “A Quick Tutorial To Get Started” on line 11 and the equals signs defining the second-level heading on line 12. As we are using reStructured Text Files with: master_doc = 'index' in "conf.py" my understanding is that the HTML element anchor element should be automatically generated and included in the menu bar on the left. (I have included a screenshot of the updated markdown changes in "index.rst" below to for clarity).

Originally created by @christianmckinnon on GitHub (May 18, 2024). Original GitHub issue: https://github.com/spotipy-dev/spotipy/issues/1109 **Feature Request & Issue:** When landing on the documentation page as a prospective contributor, I noticed straightaway that after the welcome message and description, we immediately dive into an example of how to interact with the Spotify API without any explicit context or separation from the above section. For a newcomer to the community, the lack of a transition here might detract from the flow of the docs. My understanding is that by placing these accessible Python code snippets directly beneath the welcome message, we can convey the ease with which a developer can get started using the library. This is unfortunately contrasted by the absence of a subheading that explicitly details what the code is intended to do. **Suggested Action:** I think a quick way to remedy this would be to simply add a new subheading, titled, “A Quick Tutorial To Get Started,” to provide separation from the welcome message, and clarity as to the purpose of the code. Specifically, this new subheading would be added after the sentence: _“Spotipy is a lightweight Python library for the Spotify Web API. With Spotipy you get full access to all of the music data provided by the Spotify platform.”_ The intention here is to improve the user-friendliness and clarity of the documentation. By directly defining the purpose of the relevant code snippets, developers can more immediately choose to engage in reading the content, or skip to a different subsection that is more related to the task they are trying to achieve. <img width="422" alt="SpotipyIssue" src="https://github.com/spotipy-dev/spotipy/assets/63783513/c5e7aacc-2179-4294-ba65-845fe0ca091e"> **Alternatives:** I am open to rewording the Section title based on suggestions from the community. **Additional Context: Proposed Solution & Pull Request:** The proposed update would take place after line 9 in the “_index.rst_” file of the “_docs_” folder (as seen below). To retain formatting consistency with the remainder of the document, I would suggest including blank spaces on lines 10 and 13, with “A Quick Tutorial To Get Started” on line 11 and the equals signs defining the second-level heading on line 12. As we are using reStructured Text Files with: `master_doc = 'index'` in "_conf.py_" my understanding is that the HTML element anchor element should be automatically generated and included in the menu bar on the left. (I have included a screenshot of the updated markdown changes in "_index.rst_" below to for clarity). <img width="402" alt="SpotipyPR" src="https://github.com/spotipy-dev/spotipy/assets/63783513/d5eedbcf-3dee-469c-9bae-ddb1645679d6">

kerem

2026-02-28 00:00:37 +03:00

closed this issue
added the
enhancement
label

kerem commented

2026-02-28 00:00:38 +03:00

Author

Owner

@dieser-niko commented on GitHub (May 21, 2024):

There's already a restructuring underway that would solve this problem as well. See #1054.

Also, please don't use filler words. I don't mean to be rude or anything, but your issue can be compressed into a paragraph or two without losing context. The last paragraph can be removed entirely, as it is expected that everyone using git/GitHub knows how it works. You could even just open a pull request without the issue. Here's a quick rephrasing:

When landing on the documentation page, I noticed that the welcome message immediately transitions into a Spotify API example without clear separation. This lack of transition might disrupt the flow for newcomers. The accessible Python code snippets aim to show the ease of using the library but lack a subheading explaining their purpose.

Suggested Action:
Add a subheading, “A Quick Tutorial To Get Started,” after the introduction sentence to improve clarity and user-friendliness. This will help developers understand the code's purpose and navigate the documentation more effectively.

@dieser-niko commented on GitHub (May 21, 2024): There's already a restructuring underway that would solve this problem as well. See #1054. Also, please don't use filler words. I don't mean to be rude or anything, but your issue can be compressed into a paragraph or two without losing context. The last paragraph can be removed entirely, as it is expected that everyone using git/GitHub knows how it works. You could even just open a pull request without the issue. Here's a quick rephrasing: > When landing on the documentation page, I noticed that the welcome message immediately transitions into a Spotify API example without clear separation. This lack of transition might disrupt the flow for newcomers. The accessible Python code snippets aim to show the ease of using the library but lack a subheading explaining their purpose. > > **Suggested Action**: > Add a subheading, “A Quick Tutorial To Get Started,” after the introduction sentence to improve clarity and user-friendliness. This will help developers understand the code's purpose and navigate the documentation more effectively.

kerem commented

2026-02-28 00:00:38 +03:00

Author

Owner

@christianmckinnon commented on GitHub (May 21, 2024):

Got it. Thank you so much for your feedback and I will keep that in mind for future contributions!

@christianmckinnon commented on GitHub (May 21, 2024): Got it. Thank you so much for your feedback and I will keep that in mind for future contributions!