Reorganize documentation #1759
Comments
ichard26
added
the
T: documentation
|
I tend to agree @JelleZijlstra. At a minimum, each section title should make it obvious to the reader what content is contained within that section.
Transferring to a structure like this should be relatively simple. A good starting point would be allocating all the current sections to one of the new section titles, and then collating those individual sections. Just my ideas from what I've seen/read. Thanks. |
|
Okay, I'm picking this up after what seems like forever. Apologies for sorta causing this mess in the first place, I didn't really think through what I was doing last time I reorganized the docs. Now it's time for me to fix my mistakes and do it right. So, I like @J-Exodus's basic structure and I'll be working on transferring our docs to it. I'll post a draft PR when ready. |
|
This is the hierarchy I've been thinking about (WARNING: IT WILL CHANGE AS I EDIT) : suggestions and feedback are highly appreciated. Edit history
p.s. I suck at naming things so those section names are up for debate |
|
@ichard26 that sounds great! |
|
@cooperlees @zsol what do you two think of the general hierarchy I've laid down above? I want do this correctly this time :) |
|
I like it. I would personally start explaining the "Black Style"
|
Do you mean 'start by explaining the "Black Style"' (i.e. move it up) or do you mean we should start justifying why the style is like how it is? (While our style docs are outdated and need some updating, I think they do a decent job at justifying the style choices)
I thought it was implied that Perhaps the "Usage and Configuration" section should be called "Advanced Usage and Configuration"? |
After the "quick start" go straight into explaining the "Black Style" as it's a great source of question / debate etc. etc.
Yes - But I just wanted to emphasize that we keep a quick start. I personally dislike projects I have to go digging for the "Quick Start" |
|
I personally would like to keep the "Black Style" and "Getting Started" sections separated to some degree so would moving the "Black Style" section right after "Getting Started" be okay? I was also planning to add a direct link to the "Black Style" section in the "next steps" subheader, so this might be enough? I was planning to keep "Getting Started" tiny as a single page topic, so I'm struggling to find a place for a "quick start". I guess maybe a small subheader in the "Getting Started" page in the beginning for like "Hey are you a regular user of Black and want to get started quickly? If so, please read the following section, and if not, please skip." fyi, subsections denote whole files so that why "Getting Started" has zero children, it's intended to be single-paged. edit: I didn't say this explicitly, but I agree with your feedback, just that I'm struggling to do this in a manner that feels right in the current plan. Thanks for your feedback! |
|
actually putting the "Black Style" section after the "Overview" section might make more sense since it's crucial to know how Black is going to format your file when deciding to use the tool or not. |
|
I want to keep and like the sections. Was just talking about moving. I don't care if you don't to be honest. Lets not make this harder than it needs to be. The fact you're working on this is great. In the end, do what ever you think is right. No matter what you do there will always be another way with documentation and people can comment and do PRs if they feel strongly moving forward. |
|
Well yeah I get that I can't organize the docs to be perfect for everyone, but you're giving feedback and I should try to incorporate it, especially as a fellow core team member :) Apologies if my frustration with everything (IRL included) is showing through, I did not intend to brush off your feedback. I think putting some work into a draft then seeing if it reads well with how it's organized according the plan, and then iterating (while keeping your feedback in mind) would be best. You are right about a lack of attention to the organization of the content for users. My perspective is from a core team member and maintenance type of guy view point, so thanks for the reminding me to about the other group of readers :)
I mean, I would much rather deal with issues in the planning and draft stages then in the production stage so you're not really making this harder |
|
I don't know about the Sphinx template being used here, and how
The proposed sections could be divided into:
Another way of pointing out hotspots could be a kind of introductory paragraph on the home page. Maybe something like: "The Black code style is described And so on, you get the point. It could mirror the section division, but more verbosely so that the reader doesn't have to guess as much as to where everything is located. Though the proposed structure is very much an improvement! And if there are just a handful of things that you'd like to direct attention to, the paragraph needn't reference every single section. But I see this has been worked on for quite a while now, so perhaps it would be best to introduce these separately if you decide they're worth doing. How's the reorganizing going? |
It's going fine, slow progress but going well. I've been working on and off on for a quite a while as my time is limited and my attention gets pulled to more interesting things. This is how the sidebar looks right now from the local branch right now:
Unfortunately for the TOC section titles, they IMO look horrible with the theme we have right now: I was considering moving the documentation to another theme, like the RtD one or Furo (which handle TOC section titles in a decent way), but given that influences the project's branding, I wasn't looking forward to the discussion needed by that with the rest of the core team. Honestly felt easier to just ignore that debate and work on less controversial changes. Also the spacing between the untitled sections felt like a decent compromise anyway. In general, I like my structure, although the fact the changelog is at the bottom does rub me in the wrong way. I tried to order the sections to most important to the least important. Users (which make up the biggest reader chunk) will need to know Black's style (especially if they are considering to adopt Black for their project!), then how to use Black is also vital, and so on. After that we have the contributors and core team which is way smaller, so that's why their content is lower. While I like your idea to move the changelog up, I don't like your package section. It's not clear to me what such a section would be about. I'll look into the getting started set up you got, I was 50-50 on the "one super duper simple getting started document which is followed by a much more complete document" idea I've got going on. But like other than that, we decided on pretty much the same structure ahaha
👍 In general, thanks @felix-hilden for the feedback and ideas! I'll definitely take them into account if possible. |
|
Honestly, that tree looks so much cleaner even without section titles. And I agree, they do look horrible in the theme. Combined with the branding argument I don't think it's worth it to start chasing a different theme just for them. The RTD theme has the mobile user friendliness which I don't know how this theme handles, but that also feels minor. I feel the same about the change log, but if it's not a good fit right at the top with Code Style, then I think down there is the place. I intended the Package section to be all about raw information and no tutorials, other sections then being more verbose in their explanations. But it is quite vague. And yeah that seems like the way to organise it so I'm not surprised that you came up with it as well 😅 Looking good already! Get that awesome documentation! |
|
Status update (to both prove I'm actually going to finish this and also provide some context): So far I got all of the content moved over to the new structure, which is the majority of the needed work. Although there's still a bunch to do:
edit: |
|
Thanks so much for all your work @ichard26! |
|
If anyone is subscribed to this issue for some reason: I got my PR up now: GH-2174. Go have a look and provide any sort of constructive feedback if you can! Thanks in advance. |
I know I know, this is the second reorganization of the docs. I'm not saying the first one was bad or anything... but.. actually wait nah, *it was bad*. Anyway, welcome to probably my biggest commit. The main thing with this reorganization was to introduce nesting to the documentation! Having all of the docs be part of the main TOC was becoming too much. There wasn't much room to expand either. Finally, the old setup required a documentation generation step which was just annoying. The goals of this reorganization was to: 1. Significantly restructure the docs to be discoverable and understandable 2. Add room for further docs (like guides or contributing docs) 3. Get rid of the doc generation step (it was slow and frustrating) 4. Unblock other improvements and also just make contributing to the docs easier Another important change with this is that we are no longer using GitHub as a documentation host. While GitHub does support Markdown based docs actually pretty well, the lack of any features outside of GitHub Flavoured Markdown is quite limiting. ReadTheDocs is just much better suited for documentation. You can use reST, MyST, CommonMark, and all of their great features like toctrees and admonitions. Related to this change, we're adopting MyST as our flavour of Markdown. MyST introduces neat syntax extensions to Markdown that pretty much gives us the best of both worlds. The ease of use and simplicity of MD and the flexibility and expressiveness of reST. Also recommonmark is deprecated now. This switch was possible now we don't use GH as a docs host. MyST docs have to be built to really be usable / pretty, so the MD docs are going to look pretty bad on GH, but that's fine now! Another thing that should be noted is that the README has been stripped of most content since it was confusing. Users would read the README and then think some feature or bug was fixed already and is available in a release when in reality, they weren't. They were reading effectively the latest docs without knowing. See also: #1759 FYI: CommonMark is a rationalized version of Markdown syntax -- Commit history before merge: * Switch to MyST-Parser + doc config cleanup recommonmark is being deprecated in favour of MyST-Parser. This change is welcomed, especially since MyST-Parser has syntax extensions for the Commonmark standard. Effectively we get to use a language that's powerful and expressive like ReST, but get the simplicity of Markdown. The rest of this effort will be using some MyST features. This reorganization efforts aims to remove as much duplication as possible. The regeneration step once needed is gone, significantly simplifing our Sphinx documentation configuration. * Tell pipenv we replaced recommonmark for MyST-Parser Also update `docs/requirements.txt` * Delete all auto generated content * Switch prettier for mdformat (plus a few plugins) **FYI: THIS WAS EFFECTIVELY REVERTED, SEE THIRD TO LAST COMMIT** prettier doesn't support MyST's syntax extensions which are going to be used in this reorganization effort so we have to switch formatter. Unfortanately mdformat's style is different from prettier's so time to reformat the whole repo too. We're excluding .github/ISSUE_TEMPLATE because I have no idea whether its changes are safe, so let's play it safe. * Fix the heading levels in CHANGES.md + a link MyST-Parser / sphinx's linkcheck complains otherwise. * Move reference docs into a docs/contributing dir They're for contributors of Black anyway. Also added a note in the summary document warning about the lack of attention the reference has been dealing with. * Rewrite and setup the new landing page + main TOC - add some more detail about Black's beta status - add licensing info - add external links in the main TOC for GitHub, PyPI, and IRC - prepare main TOC for new structure * Break out AUTHORS into its own file Not only was the AUTHORS list quite long, this makes it easy to include it in the Sphinx docs with just a simple symlink. * Add license to docs via a simple include Yes the document is orphaned but it is linked to in the landing page (docs/index.rst). * Add "The Black Code Style" section This mostly was a restructuring commit, there has been a few updates but not many. The main goal was to split "current style" and "planned changes to the style that haven't happened yet" to avoid confusion. * Add "Getting Started" page This is basically a quick start + even more. This commit is certainly one of most creatively involved in this effort. * Add "Usage and Configuration" section This commit was as much restructuring as new content. Instead of being in one giant file, usage and configuration documentation can expand without bloating a single file. * Add "Integrations" section Just a restructuring commit ... * Add "Guides" section This is a promising area of documentation that could easily grow in the future, let's prepare for that! * Add "Contributing" section This is also another area that I expect to see significant growth in. Contributors to Black could definitely do with some more specific docs that clears up certain parts of our slightly confusing project (it's only confusing because we're getting big and old!). * Rewrite CONTRIBUTING.md to just point to RTD * Rewrite README.md to delegate most info to RTD * Address feedback + a lot of corrections and edits I know I said I wanted to do these after landing this but given there's going to be no time between this being merged and a release getting pushed, I want these changes to make it in. - drop the number flag for mdformat - to reduce diffs, see also: https://mdformat.readthedocs.io/en/stable/users/style.html#ordered-lists - the GH issue templates should be safe by mdformat, so get rid of the exclude - clarify our configuration position - i.e. stop claiming we don't have many options, instead say we want as little formatting knobs as possible - lots and lots of punctuation, spelling, and grammar corrections (thanks Jelle!) - use RTD as the source for the CHANGELOG too - visual style cleanups - add docs about our .gitignore behaviour - expand GHA Action docs - clarify we want the PR number in the CHANGELOG entry - claify Black's behaviour for with statements post Python 3.9 - italicize a bunch of "Black"s Thank you goes to Jelle, Taneli (hukkinj1 on GH), Felix (felix-hilden on GH), and Wouter (wbolster on GH) for the feedback! * Merge remote-tracking branch 'upstream/master' into reorganize-docs-v2 merge conflicts suck, although these ones weren't too bad. * Add changelog entry + fix merge conflict resolution error I consider this important enough to be worthy of a changelog entry :) * Merge branch 'master' into reorganize-docs-v2 Co-authored-by: Łukasz Langa <lukasz@langa.pl> * Actually let's continue using prettier Prettier works fine for all of the default MyST syntax so let's not rock the boat as much. Dropping the mdformat commit was merge-conflict filled so here's additional commit instead. * Address Cooper's, Taneli's, and Jelle's feedback Lots of wording improvements by Cooper. Taneli suggested to disable the enabled by default MyST syntax not supported by Prettier and I agreed. And Jelle found one more spelling error! * More minor fixes
I feel like the current documentation isn't very well organized. It has a lot of pages and it's not obvious where to document things like
.gitignoresupport (#1734). Here's the sections we have right now:The line wrapping makes it hard to see individual sections, and a lot of them are about fairly minor issues.
Some ideas:
pyproject.tomlshould be renamed to "Configuration" and also cover other ways of configuring Black, like gitignore files and command-line optionsPlease comment if you have other ideas (or if you think I'm all wrong here and the current organization is fine).
The text was updated successfully, but these errors were encountered: