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
+17-15Lines changed: 17 additions & 15 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,32 +1,34 @@
1
-
# General
1
+
# Updating the API documentation
2
+
3
+
## General
2
4
3
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).
4
6
5
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.
6
8
7
-
## Including a repository to be documented
9
+
###Including a repository to be documented
8
10
9
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).
10
12
11
13
To get a project included:
12
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
13
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.
14
16
15
-
## Including example JSON
17
+
###Including example JSON
16
18
17
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:
18
20
19
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.
20
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.
21
23
- Raise a pullrequest to min with the changes.
22
24
23
-
# API generation
25
+
##API generation
24
26
25
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.
26
28
27
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).
28
30
29
-
## Steps to update the docs manually
31
+
###Steps to update the docs manually
30
32
31
33
If you want to update the api docs manually, please follow the steps below
32
34
@@ -47,11 +49,11 @@ If you want to update the api docs manually, please follow the steps below
47
49
1. Raise a pullrequest to main with the changes
48
50
49
51
50
-
## APIGenerator
52
+
###APIGenerator
51
53
52
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.
53
55
54
-
### Overview
56
+
####Overview
55
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:
56
58
- Compiled oM dlls to extract:
57
59
- Name and namespace of the type
@@ -69,15 +71,15 @@ The APIGenerator solution is a single projectconsole app, generating a .exe app
69
71
- Only availible for types where it has been explicitly added. See [Including example JSON](#including-example-json)
70
72
71
73
72
-
### Program steps
74
+
####Program steps
73
75
74
-
#### Load settings
76
+
#####Load settings
75
77
Parses the oM_categorisation.csv file to check for oMs to be documented
76
78
77
-
#### Load Engine assemblies
79
+
#####Load Engine assemblies
78
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).
79
81
80
-
#### Extract extention methods
82
+
#####Extract extention methods
81
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:
82
84
83
85
1. Are Query methods
@@ -87,18 +89,18 @@ This step extracts all extention methods that could be seen as Derived propertie
87
89
88
90
All methods that match this criteria will be added as derived properties to the class matching the first input parameter.
89
91
90
-
#### Load oM assemblies
92
+
#####Load oM assemblies
91
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).
92
94
93
-
#### Map types:
95
+
#####Map types:
94
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.
95
97
96
-
#### Generate markdown
98
+
#####Generate markdown
97
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:
98
100
1. Is _not_ abstract AND sealed (filters out autogenerated types)
99
101
1. Is assignable from IObject OR an enum
100
102
101
-
### Program structure
103
+
####Program structure
102
104
103
105
The program has been split into multiple files, trying to categorise by similar actions. A full description of all files will not be given here, but the code can be reviewed in place.
0 commit comments