Merge pull request plone#1455 from plone/plone.app.dexterity-init

Prepare for plone.app.dexterity docs

Author: stevepiercy

docs/backend/behaviors.md

@@ -34,6 +34,8 @@ A key feature of behaviors is that they allow encapsulating functionality so tha
 Overall, behaviors are an important part of the Plone content management system and allow for powerful customization and extensibility of content objects.
 
 
+(backend-built-in-behaviors-label)=
+
 ## Built-in behaviors
 
 To view a complete list of built-in behaviors, browse to {guilabel}`Content Types` control panel, then click {guilabel}`Page` (or any other content type), then {guilabel}`Behaviors`.

docs/backend/content-types.md docs/backend/content-types/index.mddocs/backend/content-types.md renamed to docs/backend/content-types/index.md

@@ -19,7 +19,7 @@ Insert introduction here.
 :maxdepth: 2
 configuration-registry
 control-panels
-content-types
+content-types/index
 behaviors
 annotations
 vocabularies

docs/backend/index.md

@@ -15,6 +15,43 @@ This guide is for administrators of Plone Documentation.
 It covers automated deployments, hosting, automated testing, previewing, and importing external package documentation into Plone Documentation.
 
 
+(administrators-import-docs-submodule-label)=
+
+## Importing external docs and converting to MyST
+
+This section describes how to import external projects and convert their docs to MyST.
+We did this for `plone.app.dexterity` and several other projects.
+
+1.  Create a new branch using the name of the project.
+1.  Install [rst-to-myst](https://pypi.org/project/rst-to-myst/).
+
+    ```shell
+    bin/pip install "rst-to-myst[sphinx]"
+    ```
+
+1.  Clone the project repository to the root of `plone/documentation`.
+1.  Delete any non-documentation files from the clone.
+1.  Move the documentation files and subfolders to the root of the clone, retaining the documentation structure.
+1.  Convert the reStructuredText documentation files to MyST.
+    The example commands below assume that there are files at the root of the clone and in one sub-level of nested directories.
+    For deeper nesting, insert globbing syntax for each sub-level as `**/`
+
+    ```shell
+    bin/rst2myst convert -R project/*.rst
+    bin/rst2myst convert -R project/**/*.rst
+    ```
+
+1.  Add HTML meta data to the converted files.
+
+    ```shell
+    cd project
+    ../bin/python ../docs/addMetaData.py
+    ```
+
+1.  Optionally clean up any MyST syntax.
+1.  Commit and push your branch to GitHub and create a pull request.
+
+
 (administrators-import-docs-submodule-label)=
 
 ## Importing external docs with submodules

docs/contributing/documentation/admins.md

@@ -0,0 +1,39 @@
+---
+myst:
+  html_meta:
+    "description": "How to find and add behaviors in Plone content types"
+    "property=og:description": "How to find and add behaviors in Plone content types"
+    "property=og:title": "How to find and add behaviors in Plone content types"
+    "keywords": "Plone, content types, behaviors"
+---
+
+# Behaviors
+
+This chapter describes how to find and add behaviors.
+
+Dexterity introduces the concept of *behaviors*, which are reusable bundles of functionality or form fields which can be turned on or off on a per-type basis.
+
+Each behavior has a unique interface.
+When a behavior is enabled on a type, you will be able to adapt that type to the behavior's interface.
+If the behavior is disabled, the adaptation will fail.
+The behavior interface can also be marked as an `IFormFieldsProvider`, in which case it will add fields to the standard add and edit forms.
+Finally, a behavior may imply a sub-type: a marker interface which will be dynamically provided by instances of the type for which the behavior is enabled.
+
+We will not cover writing new behaviors here, but we will show how to enable behaviors on a type.
+Writing behaviors is covered in {doc}`/backend/behaviors`.
+
+In fact, we've already seen one standard behavior applied to our example types, registered in the FTI and imported using GenericSetup.
+
+```xml
+<property name="behaviors">
+    <element value="plone.app.content.interfaces.INameFromTitle" />
+</property>
+```
+
+Other behaviors are added in the same way, by listing additional behavior interfaces as elements of the `behaviors` property.
+
+Behaviors are normally registered with the `<plone:behavior />` ZCML directive.
+When registered, a behavior will create a global utility providing `IBehavior`, which is used to provide some metadata, such as a title and description for the behavior.
+
+You can find and apply behaviors via the {guilabel}`Dexterity Content Types` control panel that is installed with [`plone.app.dexterity`](https://pypi.org/project/plone.app.dexterity/).
+For a list of standard behaviors that ship with Plone, see {ref}`backend-built-in-behaviors-label`.