bobby/open_dbm
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

[New Feature] Add web folder to support web documentation

Browse Source
This commit is contained in:
Rudy Haryanto
2022-10-04 20:17:17 +07:00
parent c27f624ca8
commit a54aa04c9b
251 changed files with 11079 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

123
docs/website/extras/odbm-doc.md Normal file
View File

@@ -0,0 +1,123 @@
---
id: odbm-doc
title: OpenDBM Documentation
---
## Summary
As book is the gate to knowledge, OpenDBM documentation is the gate to all the great features provided in this library! The OpenDBM team primary focus is how to make this library easily accessible, installable and usable in a very simple and straightforward as much as possible, and good documentation is the key to our objectives.
## Github documentation
<figure>
<img src="../docs/assets/odbm_github_doc.png" width="500" alt="OpenDBM Github documentation" />
<figcaption>OpenDBM Github documentation</figcaption>
</figure>
We want our github documentation as concise as possible. In here you can find the important information such as:
* The latest OpenDBM version in PyPI
* Unit test results which are coming from OpenDBM Code Checking Github Actions pipeline
* The code coverage that also produced by above process
Along with those informations, you can also see the OS build and test status on our documentation which produced from OpenDBM Build Checking Github Actions pipeline. This way you can check whether the last version of OpenDBM library can support which platforms
### Basic usage and other informations
We also provide a section how to install and use OpenDBM library inside our github page. But of course more detailed explanation are provided in OpenDBM Web documentation which you're probably looking right now
### TOC Table of content
We are using [DocToc](https://github.com/thlorenz/doctoc) in order to generate our table of contents. So dont change the table of content at all. If you want to add anything, just add it like a normal way, and you can use `## My Section` if you feel need to add new section for your information. After that, just generate ```doctoc .``` in the root folder and DocToc will generate the ToC immediately and include your new information seamlessly.
<figure>
<img src="../docs/assets/odbm_doctoc.png" width="500" alt="OpenDBM Github Table of Content Generator" />
<figcaption>OpenDBM Github Table of Content Generator</figcaption>
</figure>
## Web Documentation
By good probability when you read this section, you're currently looking at our web documentation. (Unless you read this from our github blob files which is still normal, no worries!)
> We are using [Docusaurus](https://docusaurus.io/) to generate this documentation as our primary objective is focus on the content and how to deliver the most straightfoward information to the community. So all the neccessary code to build this web documentation are coming from Docusaurus.
## Documentation sections
### Dashboard
When you first arrived to the OpenDBM Web documentation, you will see the concise description about what is OpenDBM and Why to use it. We also provide talks and videos that provide informations about this library. We also put the acknowledgements to those libraries that make everything is possible in this OpenDBM library
### Getting Started
This section provide informations on everything you need to know to install and use the OpenDBM. It explains about the prerequisites before you install the OpenDBM. It makes sure to leave no one behind as we provide the informations to all OS platforms.
<figure>
<img src="../docs/assets/odbm_allOs.png" width="500" alt="OpenDBM Documentation to all platforms" />
<figcaption>OpenDBM Documentation to all platforms</figcaption>
</figure>
### Variables
This section provide deeper informations about OpenDBM. There are a lot of variables you can fetch from OpenDBM, and this section provide you how to use those variables and what is the limitation on each modules. We also make sure to make annotation or reference to acknowledge other people contributions to make all this possible
### API
One of all thing about the OpenDBM generation 2 is how easy it is to use OpenDBM. We put another layer on top of the previous OpenDBM library to make it easier to use OpenDBM. All those APIs informations are provided within this section. This section is automatically generated by [pydoc](https://docs.python.org/3/library/pydoc.html) command line that executed in `.github/workflows/open_dbm-docs-deploy.yml`
<figure>
<img src="../docs/assets/pydoc-pic.png" width="100%" alt="OpenDBM Pydoc Generated Document" />
<figcaption>OpenDBM Pydoc Generated Document</figcaption>
</figure>
### Resources
This section provide all informations surrounding the OpenDBM environment. It gives you information about the pipeline, REST API, Documentation (Hi, there!) and contributing guideines.
### Blog
Within this section, you can read other people perspectives, stories and bunch of interesting stuff about OpenDBM all around the world!
## OpenDBM Web Technical Documentation
Below section will discuss in more detail about the technical aspect of OpenDBM Web documentation structure.
### How to install and run locally
Your node must be set to stable version (as of now version 16) to be able to install and run this documentation
Under the docs directory:
* ```bash yarn``` to install all the dependencies
* Then go to the the `website` directory and run the app by typing:
* Command below is for start the website for the **first time**.
```bash
cd website
pip install pydoc-markdown
pydoc-markdown -I ../opendbm/api_lib/facial_activity -m api --render-toc > website/api/facial-activity-api.md
pydoc-markdown -I ../opendbm/api_lib/movement -m api --render-toc > website/api/movement-api.md
pydoc-markdown -I ../opendbm/api_lib/verbal_acoustics -m api --render-toc > website/api/verbal-acoustics-api.md
pydoc-markdown -I ../opendbm/api_lib/speech -m api --render-toc > website/api/speech-api.md
yarn start
```
* This command is the one you execute if you have already generated dynamic documentation from pydoc-markdown
```bash
cd website && yarn start
```
### Dashboard
The dashboard page is build on top of React framework. You need only a basic React knowledge in order to change stuff in the dashboard.
### Main config file
The main config file of OpenDBM documentation is docusaurus.config.js. You can change things like:
* You can set the footer content
* You can set the `editUrl`. This parameter to define the url when you or other community members want to change this file
<figure>
<img src="../docs/assets/odbm_edit_button.png" width="300" alt="OpenDBM Edit this page button" />
<figcaption>OpenDBM Edit this page button</figcaption>
</figure>
* You can set the url, baseUrl
* in `presets[0][0]` you can set the sidebar file to show in the `getting-started` section. We can also set the limit number of versions that will be displayed in the documentation in this line `['current', ...versions.slice(0, 2)]` We will discuss about versioning deeper below
> Support too many versions will make the web deployment much slower.
* Still in the same above parameter, we can also sync the google analytic tag in `googleAnalytics.trackingID` parameter.
* in `plugins` we also can set the siderbar file to be shown in other section as well
### Versioned pages
This documentation support versioning on the library as it very important that we could provide information and retain it so community can refer to specific version for their usecase. The versions are listed under `docs/website/versions.json`. The latest version must be the first element in that array.
That versions will be referred and used in these two directories `versioned_docs` and `versioned_sidebars`. So you can edit the documentation in specific version within these directories.
Those files and sidebars file also has duplicated contents in `sidebars.json` and files under directories `docs/docs`. These files are meant for future version. So if the community using **Edit This Page** button in the pages, it will create the MR for changes related to this directory. So you can say its a temporary directory for future changes on the documentations. Later, when you create future `version-x.x` version, you can just copy paste all the files under `docs/docs` to the new version directory.
### Non Versioned pages
Right now, the non versioned pages are API, Resources, Blog. It has its own directories under docs/website. If you need new section, you can create the directory and define it in `docusaurus.config.js`.
### Navigation (Sidebar and page ID)
In the `version-xx-sidebars.json`, you can define the sidebar and the IDs of pages that you want to categorize. You can set the id inside the page i.e.
```
id: action-units
title: Actions Units
```