Skip to content

Latest commit

 

History

History
194 lines (142 loc) · 6.82 KB

directory-structure.md

File metadata and controls

194 lines (142 loc) · 6.82 KB

Directory Structure

Here are guidelines for directory structure and naming conventions in this repository.

An organized structure and naming convention makes it easier for visitors to find the relevant information, and for contributors to submit pull requests. This repository also serves as the data source for a front-end site Zaber Code Examples. It is important to adhere to a consistent naming convention because it will enable the website to index, parse, and display the examples automatically.

Here's an overview of the directory structure, with explanation of the individual files and directories to follow.

zabertech/zaber-examples/
│
├── .editorconfig
├── .gitignore
├── LICENSE
├── README.md
├── .github/
│   └── workflows
│       └──check_examples.yml
│   
├── docs/
│   ├── CONTRIBUTING.md
│   ├── cpp.md
│   ├── csharp.md
│   ├── directory-structure.md
│   ├── example-subdirectory-naming.md
│   ├── java.md
│   ├── matlab.md
│   ├── pull-requests.md
│   ├── python.md
│   ├── readme-guidelines.md
│   ├── typescript.md
│   ├── virtual-environment.md
│   └── img/
│
├── examples/
│   ├── _template/
│   │   ├── README.md
│   │   ├── cpp/
│   │   ├── csharp/
│   │   ├── img/
│   │   ├── javascript/
│   │   ├── python_pdm/
│   │   └── python_pipenv/
│   │
│   ├── categoryname1_example_name1/
│   ├── categoryname1_example_name2/
│   ├── category_name2_another_example/
│   ├── ...
│   └── <category_name>_<example_name>/
│       ├── README.md
│       ├── csharp/
│       │   ├── ...
│       │   └── ...
│       ├── img/
│       └── python/
│           ├── Pipfile
│           ├── Pipfile.lock
│           └── main.py
│
└── tools/
    └── check_examples
        ├── README.md
        ├── check.py
        └── ...

Files and Directories under (root)

These are files and directories found under the root of the zaber-examples repository.

.editorconfig

This is a simple configuration file that sets some basic coding styles in your code editor or IDE. For more information visit https://editorconfig.org/

.gitignore

This file tells git which files should not be checked into the repository. This .gitignore file within this repository should only be specific to the project - the languages, frameworks, linters, and files generated by the build process.

This file may also contain OS, code-editor, or IDE specific items that relate to the specific setup of the user, although best practice is to exclude those files by setting up a global .gitignore specific to your system.

However, for simplicity it is okay to put those files in the project .gitignore.

For further reading, see the following articles:

LICENSE

This is where you will find the license terms and conditions of using this repository.

Please note that if you are contributing to the repository, you are agreeing that your contributions will also be governed by the same license.

README.md

This is the main documentation that a visitor will see on the home page of the repository.

Directory /docs/

This directory contains documentation and guidelines that applies to all of the examples.

CONTRIBUTING.md

This is the starting point if you want to contribute examples or bug fixes to this repository.

directory-structure.md

This file itself. Gives a "sitemap" of all the files within this repository.

example-subdirectory-naming.md

Describe the naming convention for example subdirectories.

pull-requests.md

Instructions on how to branch and initiate a pull request to get your contribution reviewed and merged into the repository.

readme-guidelines.md

Guideline on how to write a README.md file for each example. This is the documentation that a visitor will see when they navigate to the example subdirectory.

(language).md

Each language has a document outlining the coding style and best practices to follow for the example code in this repository, including recommendation for linters, virtual environment, setup, etc. For example, python.md.

Directory examples/

This directory contains all the example subdirectories.

Subdirectory _template/

This is a template for setting up a new example subdirectory. Make a copy of this template and rename it to make a start contributing to a new example.

Example Subirectories <category_name>_<example_name>/

These are where all the example lives, each one self-contained in its own subdirectory. See Example Subdirectory Naming Convention for more detail on naming guidelines.

README.md

This is the README.md file for each example subdirectory. It contains example-specific explanations and documentation. This file is both meant to be read by human visitors, and also parsed by machine to be displayed on Zaber's developer documentation website. Please see README Guidelines on how to write the file to be useful for both people and machine.

img/

Subdirectory for where all the images and figures refereneced in README.md live.

Language Subdirectories

Each example subdirectory may contain examples in multiple languages.

Some examples are translated into several programming languages. If this is the case, the code for each translation should be in a subdirectory of the main project named for the implementation language.

For consistency, please use the following language subdirectories names. If you want to contribute to a language not listed here please add it to the list:

  • python/
  • matlab/
  • csharp/
  • cpp/
  • javascript/
  • typescript/
  • java/
  • octave/

Directory tools/

This directory contains tools used for CI/CD, and maintenance of this repository.

Subdirectory check_examples

A python script for running linters on examples. This script is also called as part of the CI runner script.