Skip to content

Commit 36665ee

Browse files
committed
Fix titels of update API docs
1 parent 1d90285 commit 36665ee

File tree

1 file changed

+17
-15
lines changed

1 file changed

+17
-15
lines changed

docs/Contributing/Updating-the-API-documentation.md

Lines changed: 17 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -1,32 +1,34 @@
1-
# General
1+
# Updating the API documentation
2+
3+
## General
24

35
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).
46

57
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.
68

7-
## Including a repository to be documented
9+
### Including a repository to be documented
810

911
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).
1012

1113
To get a project included:
1214
- 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
1315
- 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.
1416

15-
## Including example JSON
17+
### Including example JSON
1618

1719
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:
1820

1921
- 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.
2022
- 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.
2123
- Raise a pullrequest to min with the changes.
2224

23-
# API generation
25+
## API generation
2426

2527
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.
2628

2729
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).
2830

29-
## Steps to update the docs manually
31+
### Steps to update the docs manually
3032

3133
If you want to update the api docs manually, please follow the steps below
3234

@@ -47,11 +49,11 @@ If you want to update the api docs manually, please follow the steps below
4749
1. Raise a pullrequest to main with the changes
4850

4951

50-
## APIGenerator
52+
### APIGenerator
5153

5254
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.
5355

54-
### Overview
56+
#### Overview
5557
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:
5658
- Compiled oM dlls to extract:
5759
- Name and namespace of the type
@@ -69,15 +71,15 @@ The APIGenerator solution is a single projectconsole app, generating a .exe app
6971
- Only availible for types where it has been explicitly added. See [Including example JSON](#including-example-json)
7072

7173

72-
### Program steps
74+
#### Program steps
7375

74-
#### Load settings
76+
##### Load settings
7577
Parses the oM_categorisation.csv file to check for oMs to be documented
7678

77-
#### Load Engine assemblies
79+
##### Load Engine assemblies
7880
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).
7981

80-
#### Extract extention methods
82+
##### Extract extention methods
8183
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:
8284

8385
1. Are Query methods
@@ -87,18 +89,18 @@ This step extracts all extention methods that could be seen as Derived propertie
8789

8890
All methods that match this criteria will be added as derived properties to the class matching the first input parameter.
8991

90-
#### Load oM assemblies
92+
##### Load oM assemblies
9193
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).
9294

93-
#### Map types:
95+
##### Map types:
9496
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.
9597

96-
#### Generate markdown
98+
##### Generate markdown
9799
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:
98100
1. Is _not_ abstract AND sealed (filters out autogenerated types)
99101
1. Is assignable from IObject OR an enum
100102

101-
### Program structure
103+
#### Program structure
102104

103105
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.
104106

0 commit comments

Comments
 (0)