You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/Contributing/Updating-the-API-documentation.md
+22-22Lines changed: 22 additions & 22 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -4,71 +4,71 @@
4
4
5
5
The [BHoM API](https://bhom.xyz/api/oM/) documentation is built using mkdocs, which is the same documentation library that is used to generate the general documentation. For more information about this, please see [Editing the documentation](../Editing-the-documentation).
6
6
7
-
The [BHoM API](https://bhom.xyz/api/oM/) built up automatically [generated markdown pages](#api-generation), one per class. The md files are stored in the [api repo](https://github.com/BHoM/api) under the [docs/oM](https://github.com/BHoM/api/tree/main/docs/oM) folder. The api website is automatically being updated via github actions as soon as any changes to the files is pushed to the main branch on the repository.
7
+
The [BHoM API](https://bhom.xyz/api/oM/)is built up automatically [generated markdown pages](#api-generation), one per class. The md files are stored in the [api repo](https://github.com/BHoM/api) under the [docs/oM](https://github.com/BHoM/api/tree/main/docs/oM) folder. The api website is automatically updated via github actions as soon as any changes to the files are pushed to the main branch on the repository.
8
8
9
9
### Including a repository to be documented
10
10
11
-
The repositories and projects to be documented is controlled via the [categorisation](https://github.com/BHoM/api/blob/main/APIGenerator/APIGenerator/oM_categorisation.csv) csv file as well as the [Repos](https://github.com/BHoM/api/blob/main/APIGenerator/APIGenerator/Repos.txt).
11
+
The repositories and projects to be documented are controlled via the [categorisation](https://github.com/BHoM/api/blob/main/APIGenerator/APIGenerator/oM_categorisation.csv) csv file as well as the [Repos](https://github.com/BHoM/api/blob/main/APIGenerator/APIGenerator/Repos.txt).
12
12
13
13
To get a project included:
14
14
- Ensure the repo it belongs to is in the [Repos](https://github.com/BHoM/api/blob/main/APIGenerator/APIGenerator/Repos.txt). If not, add it, and make sure to put it after all repos it depends on for building
15
-
- Add it to the list of projects in the [categorisation](https://github.com/BHoM/api/blob/main/APIGenerator/APIGenerator/oM_categorisation.csv) file. Make sure you use one of the pre-exiting categorisations, and make sure that the last field is set to true. If you repo contains more than one oM and you just want one of them to be documented, then please add it to the list and set the "To be documented" flag to false.
15
+
- Add it to the list of projects in the [categorisation](https://github.com/BHoM/api/blob/main/APIGenerator/APIGenerator/oM_categorisation.csv) file. Make sure you use one of the pre-existing categorisations, and make sure that the last field is set to true. If your repo contains more than one oM and you just want one of them to be documented, then please add it to the list and set the "To be documented" flag to false.
16
16
17
17
### Including example JSON
18
18
19
19
For some classes, in particular for classes that are to be shared, it can be useful to show an example of how a BHoM JSON looks. To enable this for a particular class, please do the following:
20
20
21
21
- Generate a JSON file with a single object for the type you want to display, and name the file with the name of the type. Should generally be an as simple example as possible, that still highlights the potential complexity of the type.
22
22
- Add the file to the [Json examples](https://github.com/BHoM/api/tree/main/APIGenerator/APIGenerator/JsonExamples) page, under the folder corresponding to the name of the dll hosting the type.
23
-
- Raise a pullrequest to min with the changes.
23
+
- Raise a pull request to main with the changes.
24
24
25
25
## API generation
26
26
27
-
The api docs will be automatically be updated by [github actions](https://github.com/BHoM/api/actions/workflows/generation.yml) using the [APIGenerator](#apigenerator) project described in more detail below.
27
+
The api docs will be automatically updated by [github actions](https://github.com/BHoM/api/actions/workflows/generation.yml) using the [APIGenerator](#apigenerator) project described in more detail below.
28
28
29
-
The github action triggers every week on the night between saturday and sunday UTC, and creates a pull request if any changes are detected. For the changes to affect the live website, this PR needs to be merged. To view open PRs please see [Pull Requests](https://github.com/BHoM/api/pulls). Once the PR is merged, the website will be [automatically updated](#general).
29
+
The github action triggers every week on the night between Saturday and Sunday UTC, and creates a pull request if any changes are detected. For the changes to affect the live website, this PR needs to be merged. To view open PRs please see [Pull Requests](https://github.com/BHoM/api/pulls). Once the PR is merged, the website will be [automatically updated](#general).
30
30
31
31
### Steps to update the docs manually
32
32
33
33
If you want to update the api docs manually, please follow the steps below
34
34
35
35
1. Clone the [api](https://github.com/BHoM/api) repo
36
36
1. Ensure you have all code built and up to date in your BHoM assemblies folder.
37
-
- This could either be done by runnign an up to date installer or cloning and building all the code from source
37
+
- This could either be done by running an up to date installer or cloning and building all the code from source
38
38
- If this is done via the means of an installer, make sure any repos listed in the [categorisation](https://github.com/BHoM/api/blob/main/APIGenerator/APIGenerator/oM_categorisation.csv) file is cloned and built manually
39
39
1. Clone all listed repos in the [categorisation](https://github.com/BHoM/api/blob/main/APIGenerator/APIGenerator/oM_categorisation.csv) file into the 'Repositories' folder in the root folder of the api solution.
40
40
- If the folder does not exist, create it
41
-
-Reason the repos need to be cloned into the repository if for the github actions to function as it requires everything to be contain in the currently running repository
41
+
-The reason the repos need to be cloned into the repository is for the github actions to function as it requires everything to be contained in the currently running repository
42
42
1. Remove all subfolders in the 'docs/oM' folders, as well as their content. Be sure to _not_ delete index.md file.
43
-
-Reason for removing all files is to make sure that and class no lonbger present is also removed from the docs. This includes renaming a class or its namespace, as that technically will mean a new file added and the old one hence needs to be removed.
43
+
-The reason for removing all files is to make sure that any class no longer present is also removed from the docs. This includes renaming a class or its namespace, as that technically will mean a new file is added and the old one hence needs to be removed.
44
44
1. Open and build the [APIGenerator solution](https://github.com/BHoM/api/tree/main/APIGenerator)
45
45
1. Run the resulting exe
46
46
- Could be run by just hitting f5 in the solution in visual studio
47
47
- Inspect any messaging display for any issues
48
-
1. Inspect the changes to the files locally, recomended to inspect in github desktop
49
-
1. Raise a pullrequest to main with the changes
48
+
1. Inspect the changes to the files locally, recommended to inspect in github desktop
49
+
1. Raise a pull request to main with the changes
50
50
51
51
52
52
### APIGenerator
53
53
54
-
The for the app to function, it should be run ina subfolder of the solution file. If you simply build it and run and run it from the build location, or just hit f5 from the solution this will be the case. The reason this is required is due to the fact that the app requires access to settings files as well as the example jsons, which are linked through via finding the repo root folder, and then accessed via those paths.
54
+
For the app to function, it should be run in a subfolder of the solution file. If you simply build it and run it from the build location, or just hit f5 from the solution this will be the case. The reason this is required is due to the fact that the app requires access to settings files as well as the example jsons, which are linked through via finding the repo root folder, and then accessed via those paths.
55
55
56
56
#### Overview
57
-
The APIGenerator solution is a single projectconsole app, generating a .exe app that when run generates all the markdown files. Given the prerequisite [steps](#steps-to-update-the-docs-manually)has been set up, it willgenerate a .md file per .cs file in the oMs. To do this, it makes use of data from multiple sources:
57
+
The APIGenerator solution is a single project console app, generating a .exe app that when run generates all the markdown files. Given the prerequisite [steps](#steps-to-update-the-docs-manually)have been set up, it will generate a .md file per .cs file in the oMs. To do this, it makes use of data from multiple sources:
58
58
- Compiled oM dlls to extract:
59
59
- Name and namespace of the type
60
60
- Defining properties
61
-
- Class and interface heirachy
61
+
- Class and interface hierarchy
62
62
- Compiled Engine dlls to extract:
63
63
- Derived properties (extension methods)
64
64
-[Categorisation](https://github.com/BHoM/api/blob/main/APIGenerator/APIGenerator/oM_categorisation.csv) csv file to extract
65
-
-Categoriesation of the oM into the main defined categories
65
+
-Categorisation of the oM into the main defined categories
66
66
- Cloned files to extract:
67
-
- File heirachy to be matched for generated .md files
67
+
- File hierarchy to be matched for generated .md files
68
68
-[BHoM JSON Schema](https://github.com/BHoM/BHoM_JSONSchema) to extract:
69
-
- JSON schema of the obejcts
69
+
- JSON schema of the objects
70
70
- Json examples
71
-
- Only availible for types where it has been explicitly added. See [Including example JSON](#including-example-json)
71
+
- Only available for types where it has been explicitly added. See [Including example JSON](#including-example-json)
72
72
73
73
74
74
#### Program steps
@@ -80,10 +80,10 @@ Parses the oM_categorisation.csv file to check for oMs to be documented
80
80
Loads up all Engine dlls from the programdata folder that are in the BHoM organisation. To check the organisation, it checks the AssemblyDescriptionAttribute for the link, and makes sure it links over to a github repository in the BHoM organisation. If your Engine methods does not show up in there, please ensure your project file has been [set up properly](/docs/DevOps/Code%20Compliance%20and%20CI/Compliance%20Checks/Project-References-and-Build-Paths/#assembly-information).
81
81
82
82
##### Extract extention methods
83
-
This step extracts all extention methods that could be seen as Derived properties. The methods captured by this step are methods that fullfill the following conditions:
83
+
This step extracts all extension methods that could be seen as Derived properties. The methods captured by this step are methods that fulfill the following conditions:
84
84
85
85
1. Are Query methods
86
-
1.fullfuls one of the following:
86
+
1.fulfills one of the following:
87
87
- Have a single input parameter
88
88
- Have more than one input parameter, but all but the first have default values (optional).
89
89
@@ -93,10 +93,10 @@ All methods that match this criteria will be added as derived properties to the
93
93
Loads up all Engine dlls from the programdata folder that are in the BHoM organisation and also listed in the [Categorisation](https://github.com/BHoM/api/blob/main/APIGenerator/APIGenerator/oM_categorisation.csv) csv file. To check the organisation, it checks the AssemblyDescriptionAttribute for the link, and makes sure it links over to a github repository in the BHoM organisation. If your objects does not show up, please ensure it is listed in the csv file and please ensure your project file has been [set up properly](/docs/DevOps/Code%20Compliance%20and%20CI/Compliance%20Checks/Project-References-and-Build-Paths/#assembly-information).
94
94
95
95
##### Map types:
96
-
Maps the inheritance heirachy between the types. Stores information both about all base types (classes as well as interfaces) for the type, and also adds itself as a subtype to all of its base types.
96
+
Maps the inheritance hierarchy between the types. Stores information both about all base types (classes as well as interfaces) for the type, and also adds itself as a subtype to all of its base types.
97
97
98
98
##### Generate markdown
99
-
Loops through all files and generates a .md file per type in all the oM assemblies loaded in the [previous step](#load-om-assemblies), that fullfills the following conditions:
99
+
Loops through all files and generates a .md file per type in all the oM assemblies loaded in the [previous step](#load-om-assemblies), that fulfills the following conditions:
100
100
1. Is _not_ abstract AND sealed (filters out autogenerated types)
0 commit comments