Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Contributing review linkcheck #526

Merged
merged 34 commits into from
Sep 15, 2021
Merged

Contributing review linkcheck #526

merged 34 commits into from
Sep 15, 2021

Conversation

stevepiercy
Copy link
Contributor

No description provided.

@stevepiercy stevepiercy marked this pull request as draft September 11, 2021 09:52
@stevepiercy stevepiercy mentioned this pull request Sep 13, 2021
Closed
4 tasks
@stevepiercy stevepiercy marked this pull request as ready for review September 13, 2021 07:58
@ksuess
Copy link
Member

ksuess commented Sep 13, 2021

Would you rebase, please, thanks.

@stevepiercy
Add React to the glossary. The proper name is React, not ReactJS.
ca23ef8
@stevepiercy
Fix GitHub navigation links
8d87276
@stevepiercy
Expand Contributing to include Plone CLA/publishing permission, using…
af17893 
… GitHub, documentation quality, Plone code of conduct.

Move content about contributing to contributing/index
Add GitHub navigation image and information
@stevepiercy
Add MyST and Markdown to Glossary
65737ea
@stevepiercy
Update link to contributing.
22709b6
@stevepiercy
The guide is for any contributor, not just authors
872d0b5 
Fix proper noun case
@stevepiercy
Remove translation-related packages polib, transifex-client.
ac8ce78 
Remove sphinxcontrib-websupport because docs are static and not integrated into a web application.
Sort items.
@stevepiercy
Makefile: Fix whitespace, set output to $(BUILDDIR) instead of hard-c…
e5bffb1 
…oded `log`, add linkcheck and spellcheck to `make test`.

conf.py:
Sort extensions
Disable smartquotes
Remove obsolete .rst as a source_suffix
Remove obsolete exclude_patterns, now that we have the docs in a subdirectory `docs/`, configured `Makefile` to put items into `$(BUILDDIR)`

Remove redundant about.md file
@stevepiercy
Add a few good words for spellcheck
b3454b5
@stevepiercy
Remove unused, undocumented, and unsupported spell checking tools
f41717e
@stevepiercy
Remove duplicate words
5cb3f50
@stevepiercy
Fix link to contributing
8e828e8
@stevepiercy
Fix warning after rst to myst conversion
105936e
@stevepiercy
Improve spacing around local navigation. Items that wrapped onto mult…
50cc2f7 
…iple lines looked like multiple items without this improvement.
@stevepiercy
lower the linkcheck_timeout to 5 seconds
314bcb0
@stevepiercy
Bad developer added bad links to exclude from link check. I done fixe…
a93e8f2 
…d 'em.
@stevepiercy
Use em dash, not double hyphen
dadf190
@stevepiercy
Twitter does not redirect
1681b5e
@stevepiercy
Add gulp-cli to package.json
abbae66
@stevepiercy
mail server is two words
2837c78 
change lexer to shell
@stevepiercy
Add reStructuredText to Glossary
3264cdb
@stevepiercy
Reorganize contributing directory to focus on target audiences.
1b15906
@stevepiercy
Remove as redundant
a5c2461
@stevepiercy
Copy link
Contributor Author

stevepiercy commented Sep 14, 2021 •
edited
Loading

The only bit that could be included somewhere else is the request to add alternative text to images for accessibility reason.

Yes. As well as any other style that we want to either enforce as required, or suggest as a best practice. See #527.

I will push that change to this PR shortly.

@stevepiercy
Copy link
Contributor Author

And yes "Building the documentation" should now be in /contributing and nowhere else. I removed it from mastering 6 but not from mastering 5. This needs to be done.

See #528

@ksuess
Copy link
Member

ksuess commented Sep 14, 2021 •
edited
Loading

teaching:

Trainers should read {doc}setup-build and the trainings in {doc}/plone_training_config/instructions and {doc}/teachers-training/index.
These documents help trainers prepare for a successful training experience.

could go from /contributing/trainers to /teachers-training/index
and than delete /contributing/trainers from /contributing as this is meant for contributing not teaching.
Everything concerning teaching can stay in /teaching:

  • an intro
  • the existing teachers training.

I think /teachers-training/index.html#complete-mode-and-compact-presentation-mode can be replaced with your way better explanation of modes /contributing/setup-build.html#available-documentation-builds

my /teachers-training/index.html#setup-environment is superfluous with the added paragraph mentioned above (Trainers should read {doc}setup-build …

Than we have

  • /contributing
  • /teaching

ksuess
ksuess requested changes Sep 14, 2021
View reviewed changes
docs/contributing/authors.md Outdated Show resolved Hide resolved
docs/contributing/authors.md Outdated Show resolved Hide resolved
@ksuess
Copy link
Member

ksuess commented Sep 14, 2021 •
edited
Loading

@stevepiercy as you investigated a lot in linkcheck and check of spelling: Do you see a way to check if {figure} and {image} have alternative texts / alt attributes?

outdated. see #527

@stevepiercy
Copy link
Contributor Author

stevepiercy commented Sep 14, 2021 •
edited
Loading

Somehow my version of markup-syntax.md got obliterated when I did a rebase a couple days ago. I was able to restore it. After further thought, I'd like to keep the examples because they suggest best practices that are specific to Plone Training documentation (and they are hard to find).

I also realized while writing it that it needed to become a more generalized docs writing guide. I renamed and refactored it accordingly.

I'm working on the next comment about moving teacher stuff around. That's a great idea!

@stevepiercy
Copy link
Contributor Author

@ksuess I've completed revisions per your feedback, including #526 (comment). This is ready for another review.

@ksuess
Copy link
Member

ksuess commented Sep 15, 2021

Please correct me if I'm wrong, but I think now that we have /contributing and / teaching the one page /contributing/trainers can be deleted.

@ksuess
Copy link
Member

ksuess commented Sep 15, 2021

I would say with /contributing/trainers removed, it's good to merge.

spereverde
spereverde approved these changes Sep 15, 2021
View reviewed changes
Copy link
Member

@spereverde spereverde left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

wow, thanks for all the work and updates!
I checked it out locally and followed the new docs to build everything - all worked fine :-)

@pbauer pbauer merged commit 866fbfe into main Sep 15, 2021
@pbauer pbauer deleted the contributing-review-linkcheck branch September 15, 2021 19:29
@stevepiercy stevepiercy restored the contributing-review-linkcheck branch September 15, 2021 20:23
@stevepiercy stevepiercy deleted the contributing-review-linkcheck branch September 15, 2021 20:30
@stevepiercy
Copy link
Contributor Author

Please correct me if I'm wrong, but I think now that we have /contributing and / teaching the one page /contributing/trainers can be deleted.

Quickdraw @pbauer merged the PR before I could remove it. I'll create a new PR for that.

@stevepiercy
Copy link
Contributor Author

Actually, it appears that deleting contributing/trainers.md would delete content that does not exist elsewhere and should be moved into an appropriate location. I'll create a new issue.

@stevepiercy stevepiercy mentioned this pull request Sep 15, 2021
Closed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@ksuess ksuess ksuess approved these changes

@spereverde spereverde spereverde approved these changes

@pbauer pbauer pbauer approved these changes

Assignees
No one assigned
Labels
None yet
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.
4 participants
@stevepiercy @ksuess @pbauer @spereverde