documentation icon indicating copy to clipboard operation
documentation copied to clipboard

Adds code samples to fields and a set of documents around Entities

Open jflores1 opened this issue 3 years ago • 3 comments

Updates to the documentation that we use internally and may be useful to the community:

  1. Adds code samples to each field type in "docs/administration/fields.md"
  2. 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.
  3. 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.
  4. 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.

jflores1 avatar Feb 07 '23 02:02 jflores1

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.

yurikuzn avatar Feb 07 '23 06:02 yurikuzn

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.

jflores1 avatar Feb 12 '23 16:02 jflores1

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.

yurikuzn avatar Feb 13 '23 10:02 yurikuzn