Adds code samples to fields and a set of documents around Entities
Updates to the documentation that we use internally and may be useful to the community:
- Adds code samples to each field type in "docs/administration/fields.md"
- Creates a folder called "entity" in "development" that has JSON files reflecting all 5 Entities that ship with EspoCRM. Provides code examples of each type.
- Creates a file "entity" in the "development" folder that describes the Entities that ship with EspoCRM and links to the entity descriptions in (2). Also describes how "Labels" work and links to the "Fields" page. Provides code examples and file references.
- Also added "content.code.copy" to "features:" in mkdocs.yml so that code samples can be copied directly from a code block for quick and accurate implementation.
We added the following to "markdown_extensions" in "mkdocs.yml":
mkdocs.yml:
- admonition
- pymdownx.details
- pymdownx.superfences
theme:
features:
- content.code.copy
We use these to put code samples in "fields" in collapsible sections, so that code samples do not disrupt the flow of the document. We also use the "note" admonition throughout the entity documentation so that important notes (e.g. file references or system logic) are called out to the reader while working on Entities or fields in the backend.
Hi, Thanks for your work.
One thing I would note, that we would like to keep any detail metadata information out of the Fields article, as it's not a part of the developer docs. To avoid overwhelming a reader who is likely is not a developer. I'll take a look how it looks when built.
That makes sense. I considered putting the content in a separate article in the 'developers' section of the site, but I liked the context you had already provided, hence the choice for putting the content in an accordion.
I do think having that information is valuable (we use it all the time internally), so I'm open to moving it into a separate article (or even series of articles) if you think that makes more sense. Happy to go in any direction that meets your standards and helps other people (like me and my team) save time.
Hi, I've been quite busy. I was going to create a separate page in dev docs for metadata definitions for specific field types. There we can add example metadata excerpts.