Adding a 'Beginner Friendly CLI" version of the Getting Started Guide #5295
Conversation
There was a problem hiding this comment.
Hi Skylar. Thanks for your work on this documentation. I made a few suggestions via comments.
The most important change I would suggest is that I believe that every Windows-specific link, directory path, image, and .rst file here should be name-spaced specifically for Windows so someone in the future can add appropriate related documentation for folks who use Mac/Linux systems. For example:
guides/beginner-cli-windows.rst_static/images/windows/command.png_static/images/windows/[…]
Regarding filename capitalization, the convention in most Python-related projects is to use "kebab" case or "snake" case instead of the "camel" case used here, so for filenames I would recommend using all-lowercase and separating words with dashes.
| ---------- | ||
|
|
||
| You will need Python. | ||
| Beets works on Python 3.8 or later. |
There was a problem hiding this comment.
Instead of specifying the minimum Python version here, I think it's better to link to the Getting Started documentation and tell folks to check the minimum version there. Otherwise, when it comes time to increase the minimum Python version to 3.9, etc., someone has to remember to increment that value here as well. I think it's better to consolidate information about the minimum supported Python version in one place and then link to it to (1) prevent the information from getting out-of-date and (2) minimize work when incrementing the minimum supported Python version.
There was a problem hiding this comment.
If people are going to this page to learn that they have to install Python, I think we should just point them to the Python website. They'll have distro-specific instructions and makes sure that they'll get the latest version, which we should be encouraging them to do. Leaving the version out of it would be good moving forwards.
|
|
||
| Installing Python | ||
| ^^^^^^^^^^^^^^^^^ | ||
| 1. If you don't have it, `install Python`_ (you want at least Python 3.8). If you already have Python properly installed and the path set, you may skip this step. |
There was a problem hiding this comment.
Same here. Link to Getting Started documentation instead of specifying minimum Python version here.
|
|
||
| * This is where the path from earlier comes in. Under the 'User variables' section, double click the ``path`` variable. Then select *New*. Enter the path where you installed Python. Add ``\Scripts\`` at the end. After select OK in both the edit window and the Environment Variables window. | ||
|
|
||
| **IMPORTANT** - If you do not select OK in both windows, it will not save the update and you will have to repeate this step. |
|
|
||
| By default, a search term will match any of a handful of :ref:`common | ||
| attributes <keywordquery>` of songs. | ||
| (They're |
There was a problem hiding this comment.
Maybe fix the weird line wrapping here?
There was a problem hiding this comment.
This is a result of the linting for our docs not being done. It should be corrected automatically when the linter is run.
| Want to stay updated on beets? Follow `@b33ts`_ on Twitter to hear about progress on | ||
| new versions. | ||
|
|
||
| .. _@b33ts: https://twitter.com/b33ts |
There was a problem hiding this comment.
I highly suggest using the Fediverse (Mastodon) link instead of Twitter as the primary way to hear about news about Beets. Reasons:
- Fediverse/Mastodon is built on open source, just like Beets.
- One of the more unsavory moves at Twitter is that they now require everyone to log in just to see Beets-related news/tweets, whereas anyone can read Beets-related news on the Fediverse without having to log in.
If it were up to me, I would remove the Twitter link entirely from this documentation, just based on (2) above. But if you are determined to include a Twitter link, at the very least I recommend swapping the two, so that the Fediverse link is primary and the part below says:
Please let us know what you think of beets via `the discussion board`_ or `Twitter`_.
There was a problem hiding this comment.
Yeah, phase out Twitter. Mastodon is at least semi-active now and you'll get version release toots whenever we do a release now!
| @@ -4,6 +4,8 @@ Getting Started | |||
| Welcome to `beets`_! This guide will help you begin using it to make your music | |||
| collection better. | |||
|
|
|||
| New to the CLI? Check out our :doc:`beginner friendly</guides/beginnerCLI>` getting started guide for Windows! | |||
There was a problem hiding this comment.
I believe it would be better to name-space the documentation and thus this link to it:
/guides/beginnerCLI ➡️ /guides/beginner-cli-windows
|
Someone has already given some feedback which I generally agree with but I'll also point out that the CI linting for the docs has failed. That needs to work before any merge. Thanks for the PR! |
| ^^^^^^^^^^^^^^^^ | ||
| 2. Press the Windows key and type 'cmd', and then press enter on the Command Prompt. This will open your Command Line Interface. Type ``cd [folder name]`` that you wish to install beets into. Note that you may have to change directories a few times to get to the desired one ex. ``cd users\name\music_library``. For this example, I am saving it to my user so I do not need to change directories. | ||
|
|
||
| * Now install beets by running: ``pip install beets``. A successful install will collect and download the included libraries. |
There was a problem hiding this comment.
We now use poetry as a recommended installer and package manager.
|
|
||
| 1. You'll want to set a few basic options before you start using beets. The | ||
| :doc:`configuration </reference/config>` is stored in a text file. You | ||
| can show its location by running ``beet config -p``, though it may not |
There was a problem hiding this comment.
Maybe add in a quick word about how it will create the file for you.
| can show its location by running ``beet config -p``, though it may not | ||
| exist yet. | ||
|
|
||
| **Note:** You will need a text editor for these next steps. If you don't already have one, some popular ones are: `VS Code`_ , `Vim`_, and `Sublime`_. VS Code and Vim are free, but Sublime may come with a price tag. However, if you aren't too keen on downloading one, Windows Notepad will work in this case. |
There was a problem hiding this comment.
I don't think this is required. Windows comes with a number of text editors what will work just fine for these. We definitely don't need to be recommending a paid application.
| .. _Vim: https://www.vim.org/download.php | ||
| .. _Sublime: https://www.sublimetext.com | ||
|
|
||
| 2. Locate the path to the and open the config.yaml file. You may notice that when you search, that the file does not exist, even though the path does. To fix this, we can manually create the file within the text editor. I am using VS Code in this example. Hover over *File* in the top left corner of the window and select *Open Folder* from the drop down. Select the location that the ``beet config -p`` command returned. Once there, hover over the folder name, and select the little page and plus icon next to it. This will create the new file. We will name this file *config.yaml*. Double check that the config.yaml and the library.db are in the *same* folder. |
There was a problem hiding this comment.
Is there a reason you're not recommending beet config -e?
| * Keep your current directory structure; importing should never move or copy | ||
| files but instead just correct the tags on music. Put the line ``copy: no`` | ||
| under the ``import:`` heading in your config file to disable any copying or | ||
| renaming. Make sure to point ``directory`` at the place where your music is | ||
| currently stored. |
There was a problem hiding this comment.
Maybe change the first line; if people are completely new to beets, they might interpret this to mean that beets should never move or change files when importing. Perhaps change it to something about how if they want to preserve the original files, they should choose this.
| .. image:: ../_static/Images/configBase.png | ||
| :width: 800 | ||
|
|
||
| There are approximately six million other configuration options you can set |
There was a problem hiding this comment.
A joke is nice, but maybe not with this, just in case it scares them off about exploring more configuration options.
|
|
||
| By default, a search term will match any of a handful of :ref:`common | ||
| attributes <keywordquery>` of songs. | ||
| (They're |
There was a problem hiding this comment.
This is a result of the linting for our docs not being done. It should be corrected automatically when the linter is run.
| beet ls the magnetic fields | ||
| The Magnetic Fields - Distortion - Three-Way | ||
| The Magnetic Fields - Distortion - California Girls | ||
| The Magnetic Fields - Distortion - Old Fools | ||
| beet ls hissing gronlandic | ||
| of Montreal - Hissing Fauna, Are You the Destroyer? - Gronlandic Edit | ||
| beet ls bird | ||
| The Knife - The Knife - Bird | ||
| The Mae Shi - Terrorbird - Revelation Six | ||
| beet ls album:bird | ||
| The Mae Shi - Terrorbird - Revelation Six |
There was a problem hiding this comment.
Perhaps indent or format this as a shell output; the commands and the output look the same, makes it hard to pick out the shell commands.
| Keep Playing | ||
| ------------ | ||
|
|
||
| This is only the beginning of your long and prosperous journey with beets. To |
There was a problem hiding this comment.
Lovely, nice and upbeat.
| Please let us know what you think of beets via `the discussion board`_ or | ||
| `Mastodon`_. | ||
|
|
||
| .. _the mailing list: https://groups.google.com/group/beets-users |
There was a problem hiding this comment.
...if this mailing list is still active, I'm not on it, which would be a bit concerning. Maybe let's not encourage its use.
Description
Fixes #5259
I know documentation can be merged automatically, but I would still prefer review first in case there was anything small I didn't catch.
Thank you!
To Do
docs/to describe it.)docs/changelog.rstto the bottom of one of the lists near the top of the document.)