Picard Documentation Project

MusicBrainz Picard
1

With all the changes and additions to Picard over time, I get the sense that the on-line documentation could be improved. I’ve taken a shot at some restructuring (specifically the scripting and tagging sections) using the ReadTheDocs format to see if the access to the information could be simplified. In the process, I’ve tried to expand the descriptions of all of the scripting functions, and include usage examples for each.

This is still very much a work in progress because I need to add in most of the hyperlinks, and there are a few sections that I haven’t yet included, but I think there’s enough there for people to have a look and provide feedback.

If there is enough interest, perhaps this can be expanded to a comprehensive Picard on-line manual, complete with detailed explanations of the settings, how to do lookups, scripting and file naming, submitting information to MusicBrainz, and anything else we want to include. Picard is an extremely powerful tool, and I suspect that more people could make more effective use of it if there were more extensive documentation that is readily accessible.

During this initial conceptual development stage, I’m temporarily hosting it on one of my websites under a Picard Docs directory. Edit: I’ve now moved the whole thing to a project on GitHub with a new link to the docs. Please have a look if you’re interested, and let’s work together to improve it. Comments and suggestions are appreciated. Thanks.

13 Likes
2

I must say I like this very much. I personally would not be opposed to moving the more detailed documentation into the ReadTheDocs format. The website can still give an introduction in it’s own layout, but then link to the docs for all details. @zas and I had even chatted about this idea a while ago, but decided nothing concrete.

@zas had even started something similar in 2015 (using Sphinx.), see https://www.sphinx-doc.org/en/master/

A few thoughts from my side:

  • I think for the beginning we should strictly limit this to the area of scripting and plugins and leave all other documentation on the current website. Limiting the scope makes it more likely we will get this finished, and we can then more easily decide if it is a good idea to move other parts of the docs as well.
  • One idea I would like to follow is creating the actual documentation for scripting functions out of the Picard sources (should be doable with Sphinx). Also I think this could be a way to actually mark and extract documentation for those parts of Picard that can safely be considered plugin API.
5 Likes
3

It wasn’t my intent to replace the documentation on the website, but my long-term view was to create a comprehensive on-line user manual for Picard (that might even be able to be packaged with the code or as a separate install that could be served locally).

I agree. The next thing that we might consider is the configuration settings.

I like it, but it could be a bit of work because the current docstrings (what few there are) are more geared to how the functions fit in the codebase as opposed to how they would be used in a script. Nothing insurmountable, but something to keep in mind.

2 Likes
4

UPDATE: An initial draft of the on-line documentation project is now available for review. This also includes the documentation as PDF and epub files, available for download from the site (in the “Options” section at the bottom left corner of the screen), for those that prefer to read off-line. The site is currently posted on the github-pages portion of the documentation project on github.

One of the major additions has been to include usage examples for every scripting function built into Picard.

There are a few more sections that I have in mind to add, but are not yet there, including:

  • “How do I…” specific step-by-step instructions (e.g.: submit AcoustID fingerprints)
  • “Troubleshooting” (What to do when things go wrong…)
  • “Other helpful links” (e.g.: videos)

I’m looking for specific topic suggestions for these proposed sections.

I ask that anyone interested please have a look and let me know what you would like to see added or changed (including the outline structure), and especially if you find any errors. I am also looking for suggestions of what to include in the “Examples” section.

This is still very much a work in progress, but I think it’s far enough along to allow people to start picking at it.

Thanks for any comments or suggestions.

11 Likes
5

Great work @rdswift, thank you!

Just an idea:
Would it help to add some “real life examples” to the Glossary of Terms too?

Example (you write for albumartist:)

The musician or group of musicians performing on a release. Note that this is different for Classical Music releases, which follow the MusicBrainz Classical Style Guide, listing the composer(s) first, followed by the performers.

What about adding the 3 most used cases like “ABBA” for an ABBA-Album, “Various Artists” for a sampler album and “Johann Sebastian Bach” for a Classical Album?

6

image
I would like to download the whole documentation (to read it with my e-reader), but I can’t see a link for the PDF and the HTML link gives me a 404 error :frowning:

7

Easily done, and I don’t think it would hurt. Thanks for the suggestion.

8

Argh! I forgot to re-enable the PDF downloads after my testing, and I had typos in both the download file names. Should be working now. Sorry about that.

EDIT: It is now set to also build epub files, which are also available for download.

4 Likes
9

Also, English is currently the only language available. If there is enough interest, I’m thinking we might look at translations once the English version is “finalized”.

2 Likes
10

Wow, that is a big undertaking with impressive results.
I am sure this will be immensely helpful to many.

A thought:
Most users will land on MusicBrainz’ documentation page first when searching for scripting variables:
https://picard.musicbrainz.org/docs/scripting/

Would it perhaps be a good idea to have a web-link next to every function on that MusicBrainz page that will take you directly to the page for that function on your new github creation?

1 Like
11

When trying a search for a specific function by prepending the dollar sign, the search results will ignore the dollar sign.
Would it make sense (be possible) to have it search verbatim in such cases?

(b.t.w. I did try double brackets quotes surrounding the search, but that doesn’t seem to function here?)

12

You can use
"$title"

And title without $ and without quotes works the same way :wink: In my case, all this search strings leads to $title as first search result. “Advanced Variables” is the 3rd search result.

1 Like
13

I did try that but it doesn’t seem to have an effect here.
Also: try searching for: $if

Wouldn’t it be nice if you could just enter that, and get exactly that result?

14

I think, searching for a two letter string like “if” (or any other) doesn’t work at all.
In addition, according to a google search, the $ seems to be a VERY special character, even escaping it with \ doesn’t help.

1 Like
15

I might be misunderstanding this project, but I think the final aim/goal for this new documentation is to entirely replace what is currently on the Picard website.

4 Likes
16

I guessed that could be the case, but it looks like an enormous task.
It will probably take quite a while before before it will all be assimilated, so for that period it could be very useful to have links on the MB website directing to the github work in progress, so more users will be attended to it, profit from it’s content, and perhaps contribute to it.

1 Like
17

You’ll have to speak with the maintainers of the Picard Website regarding that. It’s not something anywhere close to being within my control. :wink:

I mean, I can submit a pull request with the necessary changes to the html code, but that would be pointless unless there was some prior approval in principle by the maintainers. Also, until this project has progressed to a stable state and is hosted in a semi-permanent environment (e.g.: on the readthedocs.io server), it’s a bit premature because all the links would likely change.

That could be an outcome and I fully support the notion, but I’m not expecting it to happen - at least not soon. For one thing, I’m not sure it is compatible with one of the stated goals for Picard 2.4 regarding auto-generated documentation for script functions from the Picard source code. The in-app script function documentation is quite good the way it is as of the new version of Picard, and meets its intended purpose; however, the documentation in the source code does not include some of the information contained in this documentation - most notably the examples - and there are formatting / presentation differences. The information serves different purposes in the different applications - in Picard it is a quick reference, and in the documentation it is a learning / teaching aid. As I mentioned to @Zas and @outsidecontext when we discussed it a few weeks ago, I am all in favor of only having one source for the information and extracting it to use in multiple applications as required, because that way you don’t have to worry about keeping parallel sources in sync. At the time, there was no agreement of what needed to be in that source (in function docstrings in the program source code), so we didn’t pursue it further.

The main reason I started this was because I was seeing so many questions and so much confusion about the use of Picard (e.g.: here in the Community Forum, on IRC, from GCI students, and so on), with no common place to point people for answers and no default source where users could begin their search. I elected to use the “Read The Docs” format because it is somewhat of a standard that many people are used to seeing and using, it allows organizing and readily searching the information, and there are tools available to support it.

I’m investing my time on the premise that, “if you build it, eventually people will use it.” I know that, if nothing else, I’m learning a lot in the process. I’m also hoping that, if it does prove its value, it might
be adopted by MetaBrainz and transferred to their repositories rather than remain an outside, third-party initiative. Whether or not this ever happens, I will still be happy to help maintain it.

2 Likes
18

That’s actually handled within the ReadTheDocs theme code for Sphinx. I can try having a look, but I have to admit that it’s not high on my list of priorities for this project. Sorry.

1 Like
19

@the_maintainers_of_the_Picard_Website

Would you agree it would be a good idea to have at least one link on MusicBrainz page about scripting to direct to this great body of work on github so to notify users of it’s existence?

1 Like
20

We should definitively think about it, as what you produced here is much better than the current documentation available on the website.

I think we can find ways to do that, the in-app documentation can serve as a basis, and we can easily associate external data (ie. formatted examples). Let’s work together on this and make it happen.
If it turns out in-app documentation for script functions wasn’t a good idea, we can still move from it.

The goal we all pursue is to provide the best documentation possible to Picard users (and contributors), so your initiative is more than welcomed.

3 Likes