The EdgeFirst Documentation provides tutorials and information related to EdgeFirst Studio, Middleware, and Platforms.

Follow these steps for deploying the documentation locally on your machine.

pip install -r requirements.txt

mkdocs serve

You should now be able to see the documentation on your browser by visiting this link http://localhost:8000/.

Alternatively, use mike which is typically used for extra verification that the links are not broken.

mike deploy -r <git branch> <version> <alias> [Example: mike deploy -r DE-1941-doc-fixes v1.0 testing-v1.0]

mike set-default <version> [Example: mike set-default v1.0]

Once deployed, run mike serve and access the documentation in this link http://localhost:8000/v1.0/.

This will create a local branch for the documentation that will show like the following below.

To delete the local branches that's created, run mike delete <identifier> [Example: mike delete DE-1941-doc-fixes]

More information for using mike can be found here.

Run a spell checker on the documentation using mkdocs build -s.

Discrete documentations allow a single doc file to appear in multiple locations. The doc file needs to be maintained once and the changes will be propagated in all pages that contains the doc file. All discrete documentations are placed under the directory /discrete. The syntax for adding the contents of the discrete doc in another doc is provided below.

Example: {% include-markdown "discrete/workflows/web.md" %}

Follow these conventions when working on the documentation.

1. Filenames should be lower case. Avoid a name like "Projects" for files and directories for example.
2. Keep images in an assets folder for better organization.
3. Use well descriptive names for the images. Avoid a name like "image-1" for example.
4. Either keep assets as a sub-folder to where the documentation using these assets lives, or a sub-folder of the root assets with the same hierarchy. (Former is currently being followed).
5. Do NOT use screenshots from private customer data in the documentation. We should be using our own custom datasets. Exception would be documentation for a specific dataset such as COCO.
6. Use powerpoint slidedeck images_with_layers.pptx to add images with drawing. Adopt a size of 1005x660 for home screen images of EdgeFirst Studio.
7. Avoid any unused images in the assets folder. Any unused images should be removed.
8. Typically images are rendered by using the macro figure() with a caption and center alignment as shown. This will also expose the image path to show via mouse hover as explained in point 9.

{{ figure("/studio/assets/user/signup-page.jpg", "Create a New Account") }}

Otherwise, standalone images with no captions or center alignment can either use the img() macro or the ![Alt Text](/path/to/image.jpg) syntax.

{{ img("/studio/assets/user/signup-page.jpg", "Create a New Account") }}

9. For production set show_image_paths: false under mkdocs.yml extra: . This will prevent the image path from being shown upon mouse hover in the docs which is used mostly for development process to ease the replacement of images.
10. Greenshot software was used to take screenshots and image annotations in this documentation.