Skip to content

Commit e339730

Browse files
MitchellShiellMitchellShiell
committed
readme update
1 parent 42f5120 commit e339730

File tree

2 files changed

+48
-182
lines changed

2 files changed

+48
-182
lines changed

‎README.md‎

Lines changed: 48 additions & 182 deletions
Original file line numberDiff line numberDiff line change
@@ -1,52 +1,12 @@
11

2-
# Bridge
2+
# Overture Docs
33

4-
Bridge is a single, easy-to-navigate hub that beautifully renders all our product documentation from the `/docs` folder of all our GitHub repositories.
4+
Overture Docs is a single, easy-to-navigate hub that beautifully renders all our product documentation from the `/docs` folder of all our GitHub repositories.
55

6-
> [!NOTE]
7-
> Overture Docs started under the name Bridge to reflect its ability to bridge information across multiple repositories. Bridge was also chosen in fitting with Overtures Orchestral theme.>
6+
![Overture Docs](./preview.png 'Docs for developers and informaticians')
87

9-
## Documentation Framework
10-
11-
Overture has three user profiles:
12-
13-
- **Software Engineers**: They build and customize Overture components for their software stack.
14-
15-
- **IT specialist**: Deploying and configuring Overture platforms.
16-
17-
- **Informaticians**: Use Overture platforms to gather, organize, explore and share data.
18-
19-
Our documentation is split up as follows:
20-
21-
| Documentation | User Profile | Description
22-
|---|---|---|
23-
| Product Documentation (Housed here) | Software Engineers & Developers | Technical resources for those working on or contributing to the project. |
24-
| Platform Guides (Overture.bio) | IT Specialists & Informaticians | Instructive guides covering platform setup, maintenance and usage for end-users and administrators. |
25-
26-
## How Overture Docs Works
27-
28-
- **Docusaurus**: We use Docusaurus to render the site, providing a sleek and navigable interface for our documentation.
29-
30-
- **Markdown Files**: All documentation content is stored as markdown files in the `/website/docs` directory.
31-
32-
- **Git Submodules**: We use Git submodules to store and track all our GitHub repositories within one main repository. All submodules can be found in the `submodule` folder.
33-
34-
- **Symlinks**: Only the necessary documentation files are symlinked from the submodules in the `submodule` folder to the `/website/docs` directory. This allows us to import only the required markdown content that Docusaurus needs.
35-
36-
## Benefits of this Setup
37-
38-
- **A Centralized Resource for Decentralized Documentation**: A single, easy-to-navigate hub displaying all our developer documentation while keeping all documentation markdown files within their respective repositories.
39-
40-
- **Consistent**: Enables us to easily ensure all documentation follows the same standards across different projects.
41-
42-
- **Easy to Maintain**: Updates to any of the individual project repositories `/docs` folders are automatically reflected here.
43-
44-
- **Robust Error Handling**: Docusaurus has excellent error catching, particularly for broken and missing links, reducing the need for manual testing.
45-
46-
![Pro Tip](./website/docs/03-other-software/images/proTip.png 'Use Overture Docs repo to search across all Overture repos')
47-
48-
> [!TIP]
49-
> The Overture Docs repo contains everything, therefore finding & tracking links and content across all our repos has never been easier.
8+
> [!NOTE]
9+
> Detailed information on this repository see it relevant documentation page linked here
5010
5111
## Getting Started
5212

@@ -70,161 +30,67 @@ Start the server
7030
npm start
7131
```
7232

73-
> **Note:** Docusaurus requires node version 18 or higher
74-
75-
### Adding Submodules
76-
77-
Use the following command from the submodules directory to add a new submodule:
78-
79-
```bash
80-
git submodule add -b <branchName> <GitHub repository URL> module_name
81-
```
82-
83-
This will automatically update the `.gitmodules` file located in the root directory.
84-
85-
### Updating Submodules
86-
87-
To pull the latest changes for all submodules, including any newly added ones run:
33+
> [!IMPORTANT]
34+
> Docusaurus requires node version 18 or higher
8835
89-
```bash
90-
git submodule update --remote
91-
```
92-
93-
### Using Symlinks
94-
95-
All documentation content is stored in markdown files located within `/website/docs` while the original repositories for these markdown files are in the `submodule` folder.
96-
97-
Symlinks are used here to link only the necessary folders containing markdown files from the submodule directories.
98-
99-
The script for this is in the root directory, titled `bridge.sh`:
100-
101-
```bash
102-
ln -s ../../submodules/song/docs website/docs/Song
103-
ln -s ../../submodules/score/docs website/docs/Score
104-
```
105-
106-
This allows us to import only the necessary markdown files that Docusaurus needs. Changes to either directory are linked and reflected in both.
107-
108-
#### Getting it to run with Docusaurus
109-
110-
To run this without errors, I needed to create a plugin found in `website/docsPlugin.ts`:
111-
112-
```typescript
113-
module.exports = function(context, options) {
114-
return {
115-
name: "custom-docusaurus-plugin",
116-
configureWebpack(config, isServer, utils) {
117-
return {
118-
resolve: {
119-
symlinks: false
120-
}
121-
};
122-
}
123-
};
124-
};
125-
```
126-
127-
This plugin is imported on line 32 of the `docusaurus.config.ts`:
128-
129-
```typescript
130-
plugins: ['./docsPlugin.ts'],
131-
```
132-
133-
The source of this fix can be found [here](https://github.com/facebook/docusaurus/issues/3272#issuecomment-688409489).
134-
135-
## Globally imported Mdx components
136-
137-
We can import components by default across all our mdx files reducing the head matter when using these components in mdx documents. This can be configured from the `/src/theme/MDXComponents.ts`:
36+
## How Overture Docs Works
13837

139-
```ts title="MDXComponents.ts"
140-
import type {ComponentType} from 'react';
141-
import MDXComponents from '@theme-original/MDXComponents';
142-
import Tabs from '@theme/Tabs';
143-
import TabItem from '@theme/TabItem';
38+
- **Docusaurus**: We use Docusaurus to render the site, providing a sleek and navigable interface for our documentation.
14439

40+
- **Markdown Files**: All documentation content is stored as markdown files in the `/website/docs` directory.
14541

146-
const components: typeof MDXComponents & {
147-
Tabs: ComponentType<any>;
148-
TabItem: ComponentType<any>;
149-
DocCardList: ComponentType<any>;
150-
} = {
151-
...MDXComponents,
152-
Tabs,
153-
TabItem,
154-
DocCardList,
155-
};
42+
- **Git Submodules**: We use Git submodules to store and track all our GitHub repositories within one main repository. All submodules can be found in the `submodule` folder.
15643

157-
export default components;
158-
```
44+
- **Symlinks**: Only the necessary documentation files are symlinked from the submodules in the `submodule` folder to the `/website/docs` directory. This allows us to import only the required markdown content that Docusaurus needs.
15945

160-
## Custom Components
16146

162-
There are three custom components built for this site all located in the components directory as follows:
47+
## Repository structure
16348

16449
```
16550
.
166-
└── /src/
167-
└── components/
168-
├── FundingStatment
169-
├── SiteMap
170-
└── SwaggerAPIDoc
51+
├── /submodules/ # Core Repository Submodules
52+
│ ├── /.github/ # GitHub configurations, workflows and standards docs
53+
│ ├── /arranger/ # Arranger repository
54+
│ ├── /lectern/ # Lectern repository
55+
│ ├── /lyric/ # Lyric repository
56+
│ ├── /maestro/ # Maestro repository
57+
│ ├── /score/ # Score repository
58+
│ ├── /song/ # Song repository
59+
│ └── /stage/ # Stage repository
60+
│ └── /docs/ # Repository-specific documentation (found in every submodule repo)
61+
│
62+
└── /website/ # Documentation Website
63+
├── /community/ # Community resources and guidelines
64+
├── /docs/ # Aggregated documentation (symlinked from submodules)
65+
├── /guides/ # Overture platform user guides
66+
└── /src/ # Website source code
67+
├── /components/ # React components
68+
├── /css/ # Component-specific styles
69+
├── /theme/ # Global theme configuration and styling
70+
└── /pages/ # Static page content
17171
```
17272

173-
### Site Map
174-
175-
- The sitemap component renders the frontpage navigation of the website, organized in a mosaic layout with left and right columns
176-
- Categories can be added by extending the `const categories:` object (lines 24-45) with new entries containing:
177-
- `title`: Category display name
178-
- `description`: Brief category description
179-
- Products are defined in `const products:` array (lines 47-61) with each product requiring:
180-
- `title`: Product name
181-
- `link`: URL path
182-
- `description`: Brief description
183-
- `category`: Must match a category key
184-
- `image`: Optional icon path
185-
186-
The layout groups products into their respective categories and automatically distributes them between the left column (`core`, `development`) and right column (`platform`, `misc`, `standards`).
187-
188-
This component also includes our funding statement, the copy used can be updated directly from the component on line 90.
189-
190-
> [!NOTE] Improvement Consideration
191-
> The current implementation uses hardcoded arrays (leftColumnCategories and rightColumnCategories) for column distribution. This is not ideal however it is the simplest method to organize our site content in its ideal layout.
192-
193-
### Sidebar Funding Statement
73+
### Key Directories
19474

195-
A simple React component that displays funding attribution information on the bottom left of all sidebars. It uses CSS Modules for scoped styling (styles.module.css).
75+
- **/submodules/**: Contains all Overture core repositories as Git submodules
76+
- **/website/**: Houses the Docusaurus-powered documentation website
77+
- **/community/**: Community-focused content and resources
78+
- **/docs/**: Central location for all documentation, automatically linked from repository submodules
79+
- **/guides/**: Comprehensive platform guides and tutorials
80+
- **/src/**: Website implementation files including custom components, styling, and page content
19681

197-
> [!NOTE] Improvement Consideration
198-
> Consider making the content configurable by accepting props rather than hardcoding the grant information, allowing reuse for different funding sources.
82+
## Benefits of this Setup
19983

200-
### Swagger API Embed
84+
- **A Centralized Resource for Decentralized Documentation**: A single, easy-to-navigate hub displaying all our developer documentation while keeping all documentation markdown files within their respective repositories.
20185

202-
The `SwaggerAPIDoc` component renders API documentation completely client-side by:
86+
- **Consistent**: Enables us to easily ensure all documentation follows the same standards across different projects.
20387

204-
1. Importing local JSON specification files (`songAPI.json`, `scoreAPI.json`, `maestroAPI.json`)
205-
2. Using these static JSON files to generate the documentation UI, meaning:
206-
- No actual API calls are made
207-
- Documentation works offline
208-
- No backend connectivity required
209-
- Safe for internal/private API documentation
210-
- Specifications can be version controlled alongside the code
88+
- **Easy to Maintain**: Updates to any of the individual project repositories `/docs` folders are automatically reflected here.
21189

212-
Usage example with local JSON:
213-
```jsx
214-
// Your JSON spec file (e.g., songAPI.json)
215-
{
216-
"openapi": "3.0.0",
217-
"info": {
218-
"title": "Song API",
219-
// ... rest of your API specification
220-
}
221-
}
90+
- **Robust Error Handling**: Docusaurus has excellent error catching, particularly for broken and missing links, reducing the need for manual testing.
22291

223-
// Component usage remains the same
224-
<SwaggerAPIDoc specName="song" />
225-
```
92+
![Pro Tip](./website/docs/03-other-software/images/proTip.png 'Use Overture Docs repo to search across all Overture repos')
22693

227-
The `tryItOutEnabled={false}` setting further reinforces this by preventing any attempts to make actual API calls from the documentation interface.
94+
> [!TIP]
95+
> The Overture Docs repo contains everything, therefore finding & tracking links and content across all our repos has never been easier.
22896
229-
> [!NOTE] Improvement Consideration
230-
> Consider making the content configurable by accepting a path prop rather than having to add the spec to the component itself.

‎preview.png‎

437 KB
Loading

0 commit comments

Comments
 (0)