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.

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

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

Open
wants to merge 4 commits into
base: master
Choose a base branch
from

Conversation

jflores1
Copy link

@jflores1 jflores1 commented Feb 7, 2023

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.

@yurikuzn
Copy link
Contributor

yurikuzn commented Feb 7, 2023

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.

@jflores1
Copy link
Author

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.

@yurikuzn
Copy link
Contributor

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants