Improve docs about 'First Time Contributions'

Improve docs to make clear that people who contribute for the first time(s):

pick a ticket which is labeled
if want to write docs about something else, first open a ticket on GitHub, labeled as question and explain what and why.

If you are 'newish' it is not always clear where, why and how we do certain things in a certain way. To avoid that people invest time and motivation in 'wrong' work we should make this more clear.

I think this is already well covered in the repo's README.rst and Contributing to the documentation.

Additionally in this case, a discussion originated in the Plone Community forum. The author was informed of the process.

I can think of only a couple of minor improvements.

There exists in the footer of the Plone documentation site the following. The link should remove the #id6 because it does not exist on the target page.

About this documentation: Contribute

When you create a new Issue, you get the friendly yellow bar with a link to guidelines. However, when one clicks the link, then the page is not rendered as HTML because it lacks an extension of .md (preferred on GitHub) or .rst.

Document how to build docs in just the documentation repository, instead of via the papyrus repository.

papyrus is not meant for 'normal' people, we have already: https://docs.plone.org/about/helper_tools.html, which will updated soon with more/other solutions

For 3:

Follow the Papyrus installation instructions, making sure that you can build docs there and the virtual environment is activated.
Clone the documentation repo.
Copy both Makefile and conf.py from papyrus to documentation.
Edit Makefile: ALLSPHINXOPTS = -d build/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
Create a new directory log.
make html SPHINXBUILD=/Users/stevepiercy/projects/Plone/papyrus/bin/sphinx-build (or wherever the path to papyrus' sphinx-build is located)

'Just' the documentation will not work, since we pull in different docs from various places, this is why we add docs on how you can see your docs in the 'look like of docs.plone.org'

If you do not need the look like, why should you anyway, but for testing if you reST is valid use tools like mr.docs.

As you already can see in the 5.1 branch we are also updating CI to do that for you.

Again papyrus is only for prod builds and we are moving away from papyrus ! Sorry I do not see the point of adding this to the docs. :)

Again, no one needs/should use papyrus locally.

My intent here is to build the html docs of the documentation repo locally, ensuring that it "looks right". In other words, navigation does not get messed up, headings are at the correct level, inline markup renders as intended, and other things that pass as valid reST but do not pass human inspection. Seeing the reST rendered as HTML and viewing it in a browser is tremendously helpful.

Further, once I am satisfied with the result, then I would commit, push to my fork of the documentation repo, and submit a pull request for review.

The only way I know how to do all this work up front and locally is to use Sphinx and view the build in a web browser. If there is any other way to do this, I am open to suggestion.

I tried mr.docs, but its documentation is incomplete, which is why I used the method I know.

I have Docker already installed, then pulled the image with docker pull quay.io/tiramisu/mr.docs, but then what? The docs don't say how to run the image. This is on macOS Sierra.

Looks like I need to get some missing images from somewhere.

Clone documentation into a directory named docs.
cd <parent_directory_of_docs>
docker run --rm -v "${PWD}/docs":/build/docs:rw -u "$(id -u)":"$(id -g)" quay.io/tiramisu/mr.docs testhtml

Warning, treated as error:
/build/docs/adapt-and-extend/change-the-logo.rst:None: WARNING: image file not readable: adapt-and-extend/../_robot/change-logo-in-site-control-panel.png

Makefile:63: recipe for target 'testhtml' failed
make: *** [testhtml] Error 1

If I comment out that line, then Sphinx bails on the next missing image, and so on. Is there some place where the images exist?

Fixed with https://github.com/plone/documentation/commit/c204ca8ee85f438d1486af14ced1b3efc74083d6

If you have issue with papyrus or mr.docs. Please open issues in their repositories - Thanks !

I though this issue was about making it easier to contribute? There are missing images in this repo, so builds with any tool, whether that's papyrus, mr.docs, or Sphinx, will either have warnings or warnings that become errors. Everything else has been very well addressed and clarified with the commit, but this one detail got lost in the noise.

How can a first time contributor get the images so that docs build successfully?

I reckon I could run Papyrus to make screenshots and copy over the results, but we're supposed to move away from that.

AFAIK mr.docs does not generate screenshots. I couldn't find such a method.

I thought, oh, I can just download a .zip of the docs from Read The Docs and copy over the images, but nope, this ain't hosted on RTD.

Tried hitting the image directory, https://docs.plone.org/_images/

Curses! Foiled!

Eventually I just wgeted the whole production docs to get the images.

wget \
     --recursive \
     --no-clobber \
     --page-requisites \
     --adjust-extension \
     --convert-links \
     --restrict-file-names=windows \
     --domains docs.plone.org \
     --no-parent \
     https://docs.plone.org/

I figured out where images should go, either in _robot or _source by trying to build the docs and moving images into the correct folder whenever I got a warning.

Then I got another warning:

Warning, treated as error:
/build/docs/adapt-and-extend/custom-ct/index.rst:6: WARNING: toctree contains reference to nonexisting document u'external/plone.app.dexterity/docs/index'

Makefile:63: recipe for target 'testhtml' failed
make: *** [testhtml] Error 1

So I commented out the offending line because I have no idea where the external items would originate, and proceeded to either comment out similar errors or fix the issues.

This one used an em-dash instead of a hyphen for the "bullet".

/build/docs/adapt-and-extend/theming/barceloneta.rst:158: WARNING: Bullet list ends without a blank line; unexpected unindent.

Commented out lots of toctree references to external resources.

/build/docs/adapt-and-extend/theming/index.rst:19: WARNING: toctree contains reference to nonexisting document u'external/plone.app.theming/docs/index'

The syntax error was actually on line 685 for this one:

/build/docs/adapt-and-extend/theming/resourceregistry.rst:682: WARNING: Inline emphasis start-string without end-string.

Removed stray trailing _.

/build/docs/appendices/glossary.rst:25: WARNING: Mismatch: both interpreted text role prefix and reference suffix.

Commented out 6 .. image:: http instances, although that error could be suppressed, depending on version of Sphinx:

/build/docs/develop/addons/bobtemplates.plone/README.rst:None: WARNING: nonlocal image URI found: https://secure.travis-ci.org/plone/bobtemplates.plone.png?branch=master

/build/docs/develop/addons/components/genericsetup.rst:886: WARNING: Inline literal start-string without end-string.

Commented all instances of automodule, probably could be fixed in conf.py.

/build/docs/develop/addons/components/genericsetup.rst:1111: ERROR: Unknown directive type "automodule".

/build/docs/develop/addons/index.rst:64: WARNING: toctree contains reference to nonexisting document u'develop/addons/ajax'

/build/docs/develop/import/index.rst:45: WARNING: toctree contains reference to nonexisting document u'external/collective.transmogrifier/docs/source/index'

Commented out more bad toctree references.

/build/docs/develop/index.rst:30: WARNING: toctree contains reference to nonexisting document u'develop/coredev/docs/index'
/build/docs/develop/index.rst:80: WARNING: toctree contains reference to nonexisting document u'develop/plone.api/docs/index'
/build/docs/develop/index.rst:116: WARNING: toctree contains reference to nonexisting document u'external/plone.app.event/docs/index'

/build/docs/develop/plone/getstarted/debug_mode.rst:1: SEVERE: Title overline & underline mismatch.

Another trailing "_".

/build/docs/develop/plone/misc/commandline.rst:55: WARNING: Mismatch: both interpreted text role prefix and reference suffix.

Actually on line 461:

/build/docs/develop/plone/searching_and_indexing/query.rst:457: WARNING: Inline literal start-string without end-string.

Changed second instance to use .rst.

/build/docs/develop/plone/sessions/login.rst:3: WARNING: Duplicate explicit target name: "plonepas".

Added headings for each target link to make name unique. It might be better to use intersphinx.

/build/docs/develop/styleguide/deprecation.rst:3: WARNING: Duplicate explicit target name: "zope.deprecation".

Added missing trailing ":".

/build/docs/develop/styleguide/documentation.rst:54: WARNING: malformed hyperlink target.

Tabs are evil!

/build/docs/develop/styleguide/index.rst:8: WARNING: toctree contains reference to nonexisting document u'develop/styleguide/    :maxdepth: 2'

Another trailing "_".

/build/docs/develop/styleguide/python.rst:30: WARNING: Mismatch: both interpreted text role prefix and reference suffix.

Added "text" as code language.

/build/docs/manage/deploying/caching/varnish4.rst:366: ERROR: Error in "code-block" directive:

/build/docs/manage/deploying/zope.rst:45: WARNING: Explicit markup ends without a blank line; unexpected unindent.

Lots of messed up heading levels, hard to figure out author's intent.

/build/docs/manage/installing/installation.rst:285: SEVERE: Title level inconsistent:

Should be "note".

/build/docs/manage/upgrading/version_specific_migration/p4x_to_p5x_upgrade.rst:10: ERROR: Unknown directive type "notes".

Stray "|" on line 511.

/build/docs/manage/upgrading/version_specific_migration/p4x_to_p5x_upgrade.rst:428: ERROR: Malformed table.

Changed to "-".

/build/docs/manage/upgrading/version_specific_migration/p4x_to_p5x_upgrade.rst:562: SEVERE: Title level inconsistent:

Missing image. Commented.

/build/docs/working-with-content/introduction/setting-your-preferences.rst:None: WARNING: image file not readable: ../../_robot/personal-preferences.png

Commented.

/build/docs/working-with-content/managing-content/working-copy.rst:93: ERROR: Content block expected for the "code" directive; none found.

Added to appropriate index.rst to suppress warnings.

/build/docs/CHANGES.rst:: WARNING: document isn't included in any toctree
/build/docs/README.rst:: WARNING: document isn't included in any toctree
/build/docs/about/cherrypicking.rst:: WARNING: document isn't included in any toctree
/build/docs/about/word_choice.rst:: WARNING: document isn't included in any toctree
/build/docs/develop/addons/bobtemplates.plone/CHANGES.rst:: WARNING: document isn't included in any toctree
/build/docs/develop/addons/bobtemplates.plone/docs/LICENSE.rst:: WARNING: document isn't included in any toctree
/build/docs/sitemap.rst:: WARNING: document isn't included in any toctree

And finally.

preparing documents...
Recursion error:
maximum recursion depth exceeded in cmp

This can happen with very large or deeply nested source files.  You can carefully increase the default Python recursion limit of 1000 in conf.py with e.g.:
    import sys; sys.setrecursionlimit(1500)

At which point, I just went (ノಠ益ಠ)ノ彡┻━┻ with mr.docs.

I'm back to using Sphinx directly.

Below is the sphinx-build.log for the remaining warnings, with the path to the repo trimmed from the start of each line to reduce noise. There are 5 types of warnings:

conf.py config value type
image file not readable
missing attribute
toctree contains reference to nonexisting document
unknown document

They prevent a new contributor from successfully building the docs unless one does not turn warnings into errors. I'm not sure how you want to deal with images/screenshots and external sources.

WARNING: the config value 'version' has type `list', defaults to `str.'
adapt-and-extend/change-the-logo.rst:None: WARNING: image file not readable: adapt-and-extend/../_robot/change-logo-in-site-control-panel.png
adapt-and-extend/config/add-ons.rst:None: WARNING: image file not readable: adapt-and-extend/config/../../_robot/addon-setup.png
adapt-and-extend/config/configuration-registry.rst:None: WARNING: image file not readable: adapt-and-extend/config/../../_robot/configuration-registry.png
adapt-and-extend/config/content-settings.rst:None: WARNING: image file not readable: adapt-and-extend/config/../../_robot/content-setup.png
adapt-and-extend/config/content-settings.rst:None: WARNING: image file not readable: adapt-and-extend/config/../../_robot/content-document.png
adapt-and-extend/config/date-and-time.rst:None: WARNING: image file not readable: adapt-and-extend/config/../../_robot/date-setup.png
adapt-and-extend/config/dexterity-content-types.rst:None: WARNING: image file not readable: adapt-and-extend/config/../../_robot/dexterity-setup.png
adapt-and-extend/config/discussion.rst:None: WARNING: image file not readable: adapt-and-extend/config/../../_robot/discussion-setup.png
adapt-and-extend/config/editing.rst:None: WARNING: image file not readable: adapt-and-extend/config/../../_robot/editing-setup.png
adapt-and-extend/config/errors.rst:None: WARNING: image file not readable: adapt-and-extend/config/../../_robot/errorlog-setup.png
adapt-and-extend/config/html-filtering.rst:None: WARNING: image file not readable: adapt-and-extend/config/../../_robot/filter-setup.png
adapt-and-extend/config/image-handling.rst:None: WARNING: image file not readable: adapt-and-extend/config/../../_robot/imaging-setup.png
adapt-and-extend/config/intro.rst:None: WARNING: image file not readable: adapt-and-extend/config/../../_robot/site-overview.png
adapt-and-extend/config/language.rst:None: WARNING: image file not readable: adapt-and-extend/config/../../_robot/language-setup.png
adapt-and-extend/config/language.rst:None: WARNING: image file not readable: adapt-and-extend/config/../../_robot/language-negotiation.png
adapt-and-extend/config/mail.rst:None: WARNING: image file not readable: adapt-and-extend/config/../../_robot/mail-setup.png
adapt-and-extend/config/maintenance.rst:None: WARNING: image file not readable: adapt-and-extend/config/../../_robot/zodb-setup.png
adapt-and-extend/config/markup.rst:None: WARNING: image file not readable: adapt-and-extend/config/../../_robot/markup-setup.png
adapt-and-extend/config/navigation.rst:None: WARNING: image file not readable: adapt-and-extend/config/../../_robot/navigation-setup.png
adapt-and-extend/config/resource-registries.rst:None: WARNING: image file not readable: adapt-and-extend/config/../../_robot/resource-registry.png
adapt-and-extend/config/resource-registries.rst:None: WARNING: image file not readable: adapt-and-extend/config/../../_robot/less-variables.png
adapt-and-extend/config/search.rst:None: WARNING: image file not readable: adapt-and-extend/config/../../_robot/search-setup.png
adapt-and-extend/config/security.rst:None: WARNING: image file not readable: adapt-and-extend/config/../../_robot/security-setup.png
adapt-and-extend/config/site.rst:None: WARNING: image file not readable: adapt-and-extend/config/../../_robot/site-setup.png
adapt-and-extend/config/socialmedia.rst:None: WARNING: image file not readable: adapt-and-extend/config/../../_robot/social-setup.png
adapt-and-extend/config/syndication.rst:None: WARNING: image file not readable: adapt-and-extend/config/../../_robot/syndication-setup.png
adapt-and-extend/config/theming.rst:None: WARNING: image file not readable: adapt-and-extend/config/../../_robot/theme-setup.png
adapt-and-extend/config/tinymce.rst:None: WARNING: image file not readable: adapt-and-extend/config/../../_robot/tinymce-setup.png
adapt-and-extend/config/users-groups.rst:None: WARNING: image file not readable: adapt-and-extend/config/../../_robot/users-setup.png
adapt-and-extend/config/users-groups.rst:None: WARNING: image file not readable: adapt-and-extend/config/../../_robot/groups-setup.png
adapt-and-extend/config/users-groups.rst:None: WARNING: image file not readable: adapt-and-extend/config/../../_robot/users-settings.png
adapt-and-extend/config/users-groups.rst:None: WARNING: image file not readable: adapt-and-extend/config/../../_robot/users-fields.png
adapt-and-extend/custom-ct/index.rst:6: WARNING: toctree contains reference to nonexisting document u'external/plone.app.dexterity/docs/index'
adapt-and-extend/theming/index.rst:19: WARNING: toctree contains reference to nonexisting document u'external/plone.app.theming/docs/index'
adapt-and-extend/theming/index.rst:19: WARNING: toctree contains reference to nonexisting document u'external/diazo/docs/index'
develop/addons/components/genericsetup.rst:1734: WARNING: missing attribute mentioned in :members: or __all__: module Products.GenericSetup.rolemap, attribute importRolemap RolemapImportConfigurator
develop/import/index.rst:45: WARNING: toctree contains reference to nonexisting document u'external/collective.transmogrifier/docs/source/index'
develop/index.rst:30: WARNING: toctree contains reference to nonexisting document u'develop/coredev/docs/index'
develop/index.rst:80: WARNING: toctree contains reference to nonexisting document u'develop/plone.api/docs/index'
develop/index.rst:89: WARNING: toctree contains reference to nonexisting document u'external/plone.app.multilingual/README'
develop/index.rst:98: WARNING: toctree contains reference to nonexisting document u'external/plone.app.contenttypes/docs/README'
develop/index.rst:106: WARNING: toctree contains reference to nonexisting document u'external/plone.app.contentlisting/README'
develop/index.rst:116: WARNING: toctree contains reference to nonexisting document u'external/plone.app.event/docs/index'
develop/testing/index.rst:18: WARNING: toctree contains reference to nonexisting document u'external/plone.app.testing/docs/source/index'
develop/testing/index.rst:27: WARNING: toctree contains reference to nonexisting document u'external/plone.testing/docs/index'
develop/testing/index.rst:36: WARNING: toctree contains reference to nonexisting document u'external/plone.app.robotframework/docs/source/index'
manage/index.rst:16: WARNING: toctree contains reference to nonexisting document u'external/ansible-playbook/docs/index'
working-with-content/adding-content/adding-collections.rst:None: WARNING: image file not readable: working-with-content/adding-content/../../_robot/adding-collections_add-menu.png
working-with-content/adding-content/adding-collections.rst:None: WARNING: image file not readable: working-with-content/adding-content/../../_robot/adding-collections_add-form.png
working-with-content/adding-content/adding-collections.rst:None: WARNING: image file not readable: working-with-content/adding-content/../../_robot/collection-criteria.png
working-with-content/adding-content/adding-events.rst:None: WARNING: image file not readable: working-with-content/adding-content/../../_robot/adding-events_add-menu.png
working-with-content/adding-content/adding-events.rst:None: WARNING: image file not readable: working-with-content/adding-content/../../_robot/adding-events_add-form.png
working-with-content/adding-content/adding-files.rst:None: WARNING: image file not readable: working-with-content/adding-content/../../_robot/adding-files_add-menu.png
working-with-content/adding-content/adding-files.rst:None: WARNING: image file not readable: working-with-content/adding-content/../../_robot/adding-files_add-form.png
working-with-content/adding-content/adding-folders.rst:None: WARNING: image file not readable: working-with-content/adding-content/../../_robot/adding-folders_add-menu.png
working-with-content/adding-content/adding-folders.rst:None: WARNING: image file not readable: working-with-content/adding-content/../../_robot/adding-folders_add-form.png
working-with-content/adding-content/adding-images.rst:None: WARNING: image file not readable: working-with-content/adding-content/../../_robot/adding-images_add-menu.png
working-with-content/adding-content/adding-images.rst:None: WARNING: image file not readable: working-with-content/adding-content/../../_robot/adding-images_add-form.png
working-with-content/adding-content/adding-links.rst:None: WARNING: image file not readable: working-with-content/adding-content/../../_robot/adding-links_add-menu.png
working-with-content/adding-content/adding-links.rst:None: WARNING: image file not readable: working-with-content/adding-content/../../_robot/adding-links_add-form.png
working-with-content/adding-content/adding-new-content.rst:None: WARNING: image file not readable: working-with-content/adding-content/../../_robot/adding-content_add-menu.png
working-with-content/adding-content/adding-news-items.rst:None: WARNING: image file not readable: working-with-content/adding-content/../../_robot/adding-news-items_add-menu.png
working-with-content/adding-content/adding-news-items.rst:None: WARNING: image file not readable: working-with-content/adding-content/../../_robot/adding-news-items_add-form.png
working-with-content/adding-content/adding-pages.rst:None: WARNING: image file not readable: working-with-content/adding-content/../../_robot/adding-pages_add-menu.png
working-with-content/adding-content/adding-pages.rst:None: WARNING: image file not readable: working-with-content/adding-content/../../_robot/adding-pages_add-form.png
working-with-content/adding-content/restricting-types-in-a-folder.rst:None: WARNING: image file not readable: working-with-content/adding-content/../../_robot/show-restrictions.png
working-with-content/adding-content/restricting-types-in-a-folder.rst:None: WARNING: image file not readable: working-with-content/adding-content/../../_robot/menu-restrictions.png
working-with-content/adding-content/setting-basic-properties.rst:None: WARNING: image file not readable: working-with-content/adding-content/../../_robot/basicpropertiestabs.png
working-with-content/adding-content/setting-basic-properties.rst:None: WARNING: image file not readable: working-with-content/adding-content/../../_robot/editpagecategorization.png
working-with-content/adding-content/setting-basic-properties.rst:None: WARNING: image file not readable: working-with-content/adding-content/../../_robot/datessettings.png
working-with-content/adding-content/setting-basic-properties.rst:None: WARNING: image file not readable: working-with-content/adding-content/../../_robot/ownershippanel.png
working-with-content/adding-content/setting-basic-properties.rst:None: WARNING: image file not readable: working-with-content/adding-content/../../_robot/settingspanel.png
working-with-content/collaboration-and-workflow/advanced-control.rst:None: WARNING: image file not readable: working-with-content/collaboration-and-workflow/../../_robot/workflow-advanced-menu.png
working-with-content/collaboration-and-workflow/advanced-control.rst:None: WARNING: image file not readable: working-with-content/collaboration-and-workflow/../../_robot/workflow-advanced.png
working-with-content/collaboration-and-workflow/basic-publication-states.rst:None: WARNING: image file not readable: working-with-content/collaboration-and-workflow/../../_robot/workflow-basic.png
working-with-content/collaboration-and-workflow/basic-publication-states.rst:None: WARNING: image file not readable: working-with-content/collaboration-and-workflow/../../_robot/workflow-reject.png
working-with-content/collaboration-and-workflow/collaboration-through-sharing.rst:None: WARNING: image file not readable: working-with-content/collaboration-and-workflow/../../_robot/sharing-menu.png
working-with-content/introduction/setting-your-preferences.rst:None: WARNING: image file not readable: working-with-content/introduction/../../_robot/show-preferences.png
working-with-content/introduction/setting-your-preferences.rst:None: WARNING: image file not readable: ../../_robot/personal-preferences.png
working-with-content/introduction/setting-your-preferences.rst:None: WARNING: image file not readable: working-with-content/introduction/../../_robot/personal-information.png
working-with-content/introduction/setting-your-preferences.rst:None: WARNING: image file not readable: working-with-content/introduction/../../_robot/change-password.png
working-with-content/introduction/user-accounts-and-roles.rst:None: WARNING: image file not readable: working-with-content/introduction/../../_robot/anonymous-surfing.png
working-with-content/introduction/user-accounts-and-roles.rst:None: WARNING: image file not readable: working-with-content/introduction/../../_robot/loggedin-surfing.png
working-with-content/logging-in.rst:None: WARNING: image file not readable: working-with-content/../_robot/login-link.png
working-with-content/logging-in.rst:None: WARNING: image file not readable: working-with-content/../_robot/login-popup.png
working-with-content/managing-content/contentrules.rst:None: WARNING: image file not readable: working-with-content/managing-content/../../_robot/contentrules-start.png
working-with-content/managing-content/contentrules.rst:None: WARNING: image file not readable: working-with-content/managing-content/../../_robot/contentrules-add.png
working-with-content/managing-content/contentrules.rst:None: WARNING: image file not readable: working-with-content/managing-content/../../_robot/contentrules-conditions.png
working-with-content/managing-content/contentrules.rst:None: WARNING: image file not readable: working-with-content/managing-content/../../_robot/contentrules-assign.png
working-with-content/managing-content/cutting-copying-and-pasting-items.rst:None: WARNING: image file not readable: working-with-content/managing-content/../../_robot/foldercontents-cutpaste.png
working-with-content/managing-content/deleting-items.rst:None: WARNING: image file not readable: working-with-content/managing-content/../../_robot/foldercontents-delete.png
working-with-content/managing-content/editing-content.rst:None: WARNING: image file not readable: working-with-content/managing-content/../../_robot/edit-page.png
working-with-content/managing-content/folder-contents.rst:None: WARNING: image file not readable: working-with-content/managing-content/../../_robot/foldercontents.png
working-with-content/managing-content/folder-contents.rst:80: WARNING: image file not readable: working-with-content/managing-content/../../_robot/foldercontents-columns.png
working-with-content/managing-content/folder-contents.rst:84: WARNING: image file not readable: working-with-content/managing-content/../../_robot/foldercontents-selected.png
working-with-content/managing-content/folder-contents.rst:88: WARNING: image file not readable: working-with-content/managing-content/../../_robot/foldercontents-rearrange.png
working-with-content/managing-content/folder-contents.rst:95: WARNING: image file not readable: working-with-content/managing-content/../../_robot/foldercontents-upload.png
working-with-content/managing-content/folder-contents.rst:99: WARNING: image file not readable: working-with-content/managing-content/../../_robot/foldercontents-cut.png
working-with-content/managing-content/folder-contents.rst:99: WARNING: image file not readable: working-with-content/managing-content/../../_robot/foldercontents-copy.png
working-with-content/managing-content/folder-contents.rst:99: WARNING: image file not readable: working-with-content/managing-content/../../_robot/foldercontents-paste.png
working-with-content/managing-content/folder-contents.rst:104: WARNING: image file not readable: working-with-content/managing-content/../../_robot/foldercontents-delete.png
working-with-content/managing-content/folder-contents.rst:108: WARNING: image file not readable: working-with-content/managing-content/../../_robot/foldercontents-rename.png
working-with-content/managing-content/folder-contents.rst:115: WARNING: image file not readable: working-with-content/managing-content/../../_robot/foldercontents-tags.png
working-with-content/managing-content/folder-contents.rst:119: WARNING: image file not readable: working-with-content/managing-content/../../_robot/foldercontents-state.png
working-with-content/managing-content/folder-contents.rst:123: WARNING: image file not readable: working-with-content/managing-content/../../_robot/foldercontents-properties.png
working-with-content/managing-content/folder-contents.rst:127: WARNING: image file not readable: working-with-content/managing-content/../../_robot/foldercontents-searchbox.png
working-with-content/managing-content/folder-contents.rst:131: WARNING: image file not readable: working-with-content/managing-content/../../_robot/foldercontents-columns.png
working-with-content/managing-content/folder-contents.rst:132: WARNING: image file not readable: working-with-content/managing-content/../../_robot/foldercontents-selected.png
working-with-content/managing-content/folder-contents.rst:133: WARNING: image file not readable: working-with-content/managing-content/../../_robot/foldercontents-rearrange.png
working-with-content/managing-content/folder-contents.rst:134: WARNING: image file not readable: working-with-content/managing-content/../../_robot/foldercontents-upload.png
working-with-content/managing-content/folder-contents.rst:135: WARNING: image file not readable: working-with-content/managing-content/../../_robot/foldercontents-cut.png
working-with-content/managing-content/folder-contents.rst:136: WARNING: image file not readable: working-with-content/managing-content/../../_robot/foldercontents-copy.png
working-with-content/managing-content/folder-contents.rst:137: WARNING: image file not readable: working-with-content/managing-content/../../_robot/foldercontents-paste.png
working-with-content/managing-content/folder-contents.rst:138: WARNING: image file not readable: working-with-content/managing-content/../../_robot/foldercontents-delete.png
working-with-content/managing-content/folder-contents.rst:139: WARNING: image file not readable: working-with-content/managing-content/../../_robot/foldercontents-rename.png
working-with-content/managing-content/folder-contents.rst:140: WARNING: image file not readable: working-with-content/managing-content/../../_robot/foldercontents-tags.png
working-with-content/managing-content/folder-contents.rst:141: WARNING: image file not readable: working-with-content/managing-content/../../_robot/foldercontents-state.png
working-with-content/managing-content/folder-contents.rst:142: WARNING: image file not readable: working-with-content/managing-content/../../_robot/foldercontents-properties.png
working-with-content/managing-content/folder-contents.rst:143: WARNING: image file not readable: working-with-content/managing-content/../../_robot/foldercontents-searchbox.png
working-with-content/managing-content/folder-view.rst:None: WARNING: image file not readable: working-with-content/managing-content/../../_robot/display-menu.png
working-with-content/managing-content/reordering-items.rst:None: WARNING: image file not readable: working-with-content/managing-content/../../_robot/foldercontents-reorder.png
working-with-content/managing-content/versioning.rst:None: WARNING: image file not readable: working-with-content/managing-content/../../_robot/content-history.png
working-with-content/managing-content/working-copy.rst:None: WARNING: image file not readable: working-with-content/managing-content/../../_robot/working-copy_checkout.png
working-with-content/managing-content/working-copy.rst:None: WARNING: image file not readable: working-with-content/managing-content/../../_robot/working-copy_checkout-notification.png
working-with-content/managing-content/working-copy.rst:None: WARNING: image file not readable: working-with-content/managing-content/../../_robot/working-copy_locked.png
working-with-content/managing-content/working-copy.rst:None: WARNING: image file not readable: working-with-content/managing-content/../../_robot/working-copy_checkin.png
working-with-content/managing-content/working-copy.rst:None: WARNING: image file not readable: working-with-content/managing-content/../../_robot/working-copy_checkin-form.png
working-with-content/managing-content/working-copy.rst:None: WARNING: image file not readable: working-with-content/managing-content/../../_robot/working-copy_cancel-checkout.png
working-with-content/managing-content/working-copy.rst:None: WARNING: image file not readable: working-with-content/managing-content/../../_robot/working-copy_cancel-checkout-form.png
working-with-content/portlet-management/managing-portlets.rst:None: WARNING: image file not readable: working-with-content/portlet-management/../../_robot/portlet-menu.png
working-with-content/portlet-management/managing-portlets.rst:None: WARNING: image file not readable: working-with-content/portlet-management/../../_robot/portlet-footer.png
working-with-content/using-tinymce-as-visual-editor/basics.rst:None: WARNING: image file not readable: working-with-content/using-tinymce-as-visual-editor/../../_robot/tinymce.png
working-with-content/using-tinymce-as-visual-editor/inserting-images.rst:None: WARNING: image file not readable: working-with-content/using-tinymce-as-visual-editor/../../_robot/tinymce-imgbutton.png
working-with-content/using-tinymce-as-visual-editor/inserting-images.rst:None: WARNING: image file not readable: working-with-content/using-tinymce-as-visual-editor/../../_robot/tinymce-imgdialog.png
working-with-content/using-tinymce-as-visual-editor/inserting-links.rst:None: WARNING: image file not readable: working-with-content/using-tinymce-as-visual-editor/../../_robot/tinymce-linkbutton.png
working-with-content/using-tinymce-as-visual-editor/inserting-links.rst:None: WARNING: image file not readable: working-with-content/using-tinymce-as-visual-editor/../../_robot/tinymce-linkdialog.png
working-with-content/using-tinymce-as-visual-editor/inserting-tables.rst:None: WARNING: image file not readable: working-with-content/using-tinymce-as-visual-editor/../../_robot/tinymce-table.png
CHANGES.rst:: WARNING: document isn't included in any toctree
about/cherrypicking.rst:: WARNING: document isn't included in any toctree
about/word_choice.rst:: WARNING: document isn't included in any toctree
sitemap.rst:: WARNING: document isn't included in any toctree
develop/plone/misc/commandline.rst:223: WARNING: unknown document: /develop/plone.api/docs/env
manage/installing/installation.rst:63: WARNING: unknown document: /external/ansible-playbook/docs/index

I am really sorry that certain software is not working for you and that you are not happy.

Maybe it is time that you step back for a short moment a take a breath ?

For the beginning: All the stuff that you are reporting about sphinx build errors is already in the tracker of the docs or Papyrus, since a long time.

Papyrus:

As you may noted, my commit was for the 5.1 branch, we currently do not have a working Papyrus setup for 5.1. If you ever looked closer at the setup of Papyrus, you will have noticed that it does way more things than 'a normal Sphinx build'.

I assume that you also noticed the open tickets about Papyrus and Plone 5.1.

Further, you may also have seen the tweet or the posting on community that we are closing the 5.0 branch, meaning 5.1 is the default.

This means I will switch that on GitHub too, sometime this weekend.

Taking all this, removing Papyrus from the README, makes is easier, because we do not tell user to use something what is not working.

Yes, we know that is not ideal and we will replace that with something else asap.

Still most of the people do not need to build the whole docs, if you want to see 'your' document changes there are tools mentioned already in the docs.

Maybe this should more transparent, to make this clear.

Again this is temporary.

To sum it up:

If you try to build docs for 5.1 with Papyrus it will currently not work.

mr.docs:

First of all some of the issue you encountered have nothing to do with mr.docs,

As I already write above, I assume you looked at Papyrus, right ?

Than you already have seen that some of these 'issues' already reported in the bug tracker and have to do with Papyrus and Sphinx and not with mr.docs.

I assume you read the docs?

There it tells exactly what it is doing and how you can change that.

OOTB mr.mrdocs runs in neat picky mode, you can tell mr.docs to not do that.

As also written in the docs, mr.docs 'mounts' the docs directory (or any dir) you define in the run command, if there are no pictures in there it can't use them.

All this is written in the docs and you can see it the commands.

Summary:

I know that currently the situation is frustrating and not perfect.

Before you know start with Pyramid is doing is different and so on...

We work different than you, we have a different flow.

Our docs situation is different and we do things different, most of the time there are good reasons why we do things in a certain way.

Sometimes there are not that clear if you do not know the internals of Plone, the history of our docs and so on.

There are only a limited amount of people working on the docs, and I am really sorry, I apologize, this is not meant to offend you but I rather fix documentation build tools and the docs itself than writing this long answers on GitHub.

As I said above, I know that this is frustrating, and again I apologize but this here take too much of my already spare free time and communicating with you in this way is taking too much of my motivation.

I can't work in that way, it make me not happy and I am getting something between annoyed and really really frustrated, let me express again that this is not meant to offend you !

I want to build a complete set of warning- and error-free Plone docs on my local machine. I assumed the Plone docs team shares that goal. Is that not correct? I'm fine either way, I just want to know for sure.

If it is a goal, then I would like to help the Plone docs team create and document a set of tools that accomplishes that end, such that any ~~idiot like me~~ end user can follow along. I would be honored to participate.

Finally, maybe I'm barking up the wrong tree. Is this repo the correct one in which to report issues with building the Plone docs, or is there a more appropriate one?

Please let me know. Thank you!

Aha ....

Did you ever thought about, that maybe telling that in the beginning and then ask how you can help and maybe how and why the docs are setup, structured and so on would be a way nicer way ?

Complaining about setups which you do not know and they reasons behind it is not really a good way to start.

There are reasons why we do stuff how we do and yes not everything is perfect and lots of stuff will change, but still, maybe it is better to first have a overview and general understanding ?

I certainly think so.

Coming back to you, yes of course we want a warning and error free build, but even here, we do not jump "blind" into it.

This is 'only' one of the many goals, meaning we do that in a systematic way that we fix it and if possible add it to CI.

I rather do a bit longer over fixing all reST, error but instead I fix one and add this one to CI.

Further, reST errors are in the background for me way more important is that docs are readable, understandable, without typos and better grammar, this is still the main focus, reST errors are slightly less important for us. The idea is that over time, every time someone works on a files, the reST gets anyway better, because over the time we have more and more tests in CI.

Again, if you ever bothered to ask in the beginning, we had told you that.

Yes, this is maybe not the way how you do it on other docs, but that is the way we decided to do it, first make sure that your docs are typo free, and people understand them, second fix reST in the back.

I assumed the role of "first timer" and ran through the existing state of published procedures for contributing to documentation on the 5.0 branch (which was current at the time), then shared that experience. This was not intended to be an attack. Please don't read anything more into it.

Plone 6 docs now have an easy entry point for first time contributors. This will not be fixed in Plone 5.2.x docs.

plone / documentation

Improve docs about 'First Time Contributions' #822