Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[Docs] Refactor Docs Pages For Diataxis #6315

Merged
merged 29 commits into from
May 22, 2024
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
29 commits
Select commit Hold shift + click to select a range
f7853bd
This change creates a PR
deeleeramone Apr 15, 2024
993a982
Merge branch 'develop' into docs/diataxis-refactor
deeleeramone Apr 16, 2024
222490f
start moving stuff around
deeleeramone Apr 16, 2024
2874948
data_models/_category_.json
deeleeramone Apr 16, 2024
98a2383
reference/_category_.json
deeleeramone Apr 16, 2024
abcf031
Merge branch 'develop' into docs/diataxis-refactor
deeleeramone Apr 18, 2024
402274a
moving some stuff around
deeleeramone Apr 18, 2024
dc41da1
Introduction
IgorWounds Apr 22, 2024
27fb5cd
Documentation updates
IgorWounds Apr 29, 2024
b353da1
merge branch develop
deeleeramone Apr 30, 2024
1140273
few broken links, clean up sidebar titles for how-to
deeleeramone Apr 30, 2024
67b16b8
codespell
deeleeramone Apr 30, 2024
6f0c73b
Merge branch 'develop' into docs/diataxis-refactor
deeleeramone May 1, 2024
a5306ec
Merge branch 'develop' into docs/diataxis-refactor
jmaslek May 2, 2024
819979b
Merge branch 'develop' of https://github.com/OpenBB-finance/OpenBBTer…
deeleeramone May 3, 2024
a93aabc
quickstart - new provider extension
deeleeramone May 3, 2024
99a21db
add a comment
deeleeramone May 3, 2024
8563c73
map provider interface
deeleeramone May 3, 2024
e471997
Merge branch 'develop' into docs/diataxis-refactor
deeleeramone May 6, 2024
acf7611
quickstart for new router extension
deeleeramone May 6, 2024
b7a5c1f
Merge branch 'docs/diataxis-refactor' of https://github.com/OpenBB-fi…
deeleeramone May 6, 2024
f9f5c93
merge develop
IgorWounds May 15, 2024
f480276
[Docs] diataxis refactor refactor (#6425)
IgorWounds May 21, 2024
57bdddd
Fix broken links
piiq May 21, 2024
54c114c
Reword CLA part in the Licensing FAQ
piiq May 21, 2024
684b6d9
Merge remote-tracking branch 'OpenBB-finance/develop' into docs/diata…
hjoaquim May 22, 2024
72b10c9
Merge branch 'develop' into docs/diataxis-refactor
hjoaquim May 22, 2024
4b44e23
change titles and order suggestion - cc @IgorWounds @piiq
hjoaquim May 22, 2024
d1c94b2
Merge branch 'develop' into docs/diataxis-refactor
hjoaquim May 22, 2024
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions openbb_platform/CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -64,7 +64,7 @@ This document provides guidelines for contributing to the OpenBB Platform.
Throughout this document, we will be differentiating between two types of contributors: Developers and Contributors.

1. **Developers**: Those who are building new features or extensions for the OpenBB Platform or leveraging the OpenBB Platform.
2. **Contributors**: Those who contribute to the existing codebase, by opening a [Pull Request](#how-to-create-a-pr) thus giving back to the community.
2. **Contributors**: Those who contribute to the existing codebase, by opening a [Pull Request](#getting_started-create-a-pr) thus giving back to the community.

**Why is this distinction important?**

Expand Down Expand Up @@ -676,7 +676,7 @@ When using the OpenBB Platform on a API Interface, the types are a bit more limi

The Contributor Guidelines are intended to be a continuation of the [Developer Guidelines](#developer-guidelines). They are not a replacement, but rather an expansion, focusing specifically on those who seek to directly enhance the OpenBB Platform's codebase. It's crucial for Contributors to be familiar with both sets of guidelines to ensure a harmonious and productive engagement with the OpenBB Platform.

There are many ways to contribute to the OpenBB Platform. You can add a [new data point](#how-to-add-a-new-data-point), add a [new command](#openbb-platform-commands), add a [new visualization](/openbb_platform/extensions/charting/README.md), add a [new extension](#how-to-build-openbb-extensions), fix a bug, improve or create documentation, etc.
There are many ways to contribute to the OpenBB Platform. You can add a [new data point](#getting_started-add-a-new-data-point), add a [new command](#openbb-platform-commands), add a [new visualization](/openbb_platform/extensions/charting/README.md), add a [new extension](#getting_started-build-openbb-extensions), fix a bug, improve or create documentation, etc.

### Expectations for Contributors

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -44,7 +44,7 @@ By default, more than three symbols will draw the chart as cumulative returns fr
The tickers below are a collection of State Street Global Advisors SPDR funds, representing S&P 500 components.
The data is looking back five years.

```
```python
SPDRS = [
"SPY",
"XLE",
Expand Down Expand Up @@ -162,4 +162,5 @@ create_bar_chart(
title="S&P Energy Sector YTD Turnover Rate",
)
```

![S&P 500 Energy Sector Turnover Rate](https://github.com/OpenBB-finance/OpenBBTerminal/assets/85772166/4f59eb36-e637-4a54-87ab-e730e43baf8d)
Original file line number Diff line number Diff line change
Expand Up @@ -339,11 +339,12 @@ The `openbb-charting` extension is equipped with interactive tables, utilizing t
data = obb.equity.price.quote("AAPL,MSFT,GOOGL,META,TSLA,AMZN", provider="yfinance")
data.charting.table()
```

![Interactive Tables](https://github.com/OpenBB-finance/OpenBBTerminal/assets/85772166/77f5f812-b933-4ced-929c-c1e39b2a3eed)

External data can also be supplied, providing an opportunity to filter or apply Pandas operations before display.

```
```python
new_df = df.to_df().T
new_df.index.name="metric"
new_df.columns = new_df.loc["symbol"]
Expand Down
4 changes: 4 additions & 0 deletions website/content/platform/data_models/_category_.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
{
"label": "Data Models",
"position": 5
}
4 changes: 4 additions & 0 deletions website/content/platform/developer_guide/_category_.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
{
"label": "Developer Guide",
"position": 3
}
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
---
title: Architecture Overview
sidebar_position: 2
sidebar_position: 1
description: This guide provides insights into the architecture and components of the OpenBB Platform. It covers the key classes, import statements, and the TET pattern used in building the Fetcher classes.
keywords:
- OpenBB Platform Architecture
Expand Down Expand Up @@ -30,13 +30,13 @@ The OpenBB Platform core relies on a set of carefully selected Python libraries.
- Pandas for data manipulation and analysis.
- Pydantic for data validation and serialization using Python type annotations.
- Requests/AIOHTTP for making HTTP requests.
- Websockets for handling WebSocket connections.
- WebSockets for handling WebSocket connections.

These dependencies are specified in the `pyproject.toml` files.

### Importance Of A Lean Core

Keeping the OpenBB Platform core as lean as possible is crucial for maintaining the platform's performance, ease of use, and flexibility. A lean core means faster installation times, less memory usage, and overall better performance. It also reduces the risk of conflicts between dependencies and makes the platform easier to maintain and update.
Keeping the OpenBB Platform core as lean as possible is crucial for maintaining the its performance, ease of use, and flexibility. A lean core means faster installation times, less memory usage, and overall better performance. It also reduces the risk of conflicts between dependencies and makes the platform easier to maintain and update.

Moreover, a lean core allows for greater flexibility. Users of the platform can add additional functionality through extensions without being burdened by unnecessary core dependencies. This makes the OpenBB Platform adaptable to a wide range of use cases and requirements.

Expand Down Expand Up @@ -77,15 +77,67 @@ When using the OpenBB Platform via an API Interface, the types are a bit more co
]
```

## `QueryParams` Class
## QueryParams Class

The QueryParams class is a standardized model for handling query input parameters in the OpenBB platform. It extends the BaseModel from the Pydantic library, which provides runtime data validation and serialization.

The class includes a dictionary, `__alias_dict__`, which can be used to map the original parameter names to aliases. This can be useful when dealing with different data providers that may use different naming conventions for similar parameters.
Below is the [EquityHistorical](https://docs.openbb.co/platform/data_models/EquityHistorical) standard model.

The `__json_schema_extra__` dictionary can be used to define whether multiple items are accepted by a parameter.
```python
"""Equity Historical Price Standard Model."""

from datetime import (
date as dateType,
datetime,
)
from typing import Optional, Union

from dateutil import parser
from pydantic import Field, field_validator

from openbb_core.provider.abstract.data import Data
from openbb_core.provider.abstract.query_params import QueryParams
from openbb_core.provider.utils.descriptions import (
DATA_DESCRIPTIONS,
QUERY_DESCRIPTIONS,
)

class EquityHistoricalQueryParams(QueryParams):
"""Equity Historical Price Query."""

symbol: str = Field(description=QUERY_DESCRIPTIONS.get("symbol", ""))
interval: Optional[str] = Field(
default="1d",
description=QUERY_DESCRIPTIONS.get("interval", ""),
)
start_date: Optional[dateType] = Field(
default=None,
description=QUERY_DESCRIPTIONS.get("start_date", ""),
)
end_date: Optional[dateType] = Field(
default=None,
description=QUERY_DESCRIPTIONS.get("end_date", ""),
)

@field_validator("symbol", mode="before", check_fields=False)
@classmethod
def to_upper(cls, v: str) -> str:
"""Convert field to uppercase."""
return v.upper()
```

:::info
Note that not all possible parameters are defined here, and can be further refined in the provider-specific model.

For example, `interval` is defined as a string in the standard model, but is defined again as a `Literal` with explicit choices specific to that source. Here, it would not be possible to define all valid choices in a way that is compatible with all providers.
:::


The class can have a dictionary, `__alias_dict__`, which can be used to map the original parameter names to aliases. This can be useful when dealing with different data providers that may use different naming conventions for similar parameters.

The `__json_schema_extra__` dictionary can be used to define whether multiple items are accepted by a parameter.

``` python
__json_schema_extra__ = {
"symbol": ["multiple_items_allowed"],
"category": ["multiple_items_allowed"],
Expand All @@ -98,8 +150,7 @@ The `model_config` attribute is a `ConfigDict` instance that allows extra fields

The `model_dump` method is used to serialize the model into a dictionary. If the `__alias_dict__` is not empty, it will use the aliases defined in it for the keys in the returned dictionary. If the `__alias_dict__` is empty, it will return the original serialized model.


## `Data` Class
## Data Class

The OpenBB Standardized Data Model.

Expand All @@ -108,7 +159,9 @@ for OpenBB's data processing pipeline as it's structured to support dynamic fiel

The model leverages Pydantic's powerful validation features to ensure data integrity while
providing the flexibility to handle extra fields that are not explicitly defined in the model's
schema. This makes the `Data` class ideal for working with datasets that may have varying
schema.

This makes the `Data` class ideal for working with datasets that may have varying
structures or come from heterogeneous sources.

Key Features:
Expand Down Expand Up @@ -141,7 +194,35 @@ The class is highly extensible and can be subclassed to create more specific mod
particular datasets or domains, while still benefiting from the base functionality provided by the
`Data` class.

## `Fetcher` Class
The `Data` model for the `EquityHistorical` standard model is shown below.

```python
class EquityHistoricalData(Data):
"""Equity Historical Price Data."""

date: Union[dateType, datetime] = Field(
description=DATA_DESCRIPTIONS.get("date", "")
)
open: float = Field(description=DATA_DESCRIPTIONS.get("open", ""))
high: float = Field(description=DATA_DESCRIPTIONS.get("high", ""))
low: float = Field(description=DATA_DESCRIPTIONS.get("low", ""))
close: float = Field(description=DATA_DESCRIPTIONS.get("close", ""))
volume: Optional[Union[float, int]] = Field(
default=None, description=DATA_DESCRIPTIONS.get("volume", "")
)
vwap: Optional[float] = Field(
default=None, description=DATA_DESCRIPTIONS.get("vwap", "")
)

@field_validator("date", mode="before", check_fields=False)
def date_validate(cls, v):
"""Return formatted datetime."""
if ":" in str(v):
return parser.isoparse(str(v))
return parser.parse(str(v)).date()
```

## Fetcher Class

The `Fetcher` class is an abstract base class designed to provide a structured way to fetch data from various providers. It uses generics to allow for flexibility in the types of queries, data, and return values it handles.

Expand All @@ -164,7 +245,7 @@ The `Fetcher` class implementation is based on the [TET pattern](/platform/devel

:::

## `OBBject` Class
## OBBject Class

The OBBject class is a generic class in the OpenBB platform that represents a standardized object for handling and manipulating data fetched from various providers. It extends the `Tagged` class and uses Python's generics to allow flexibility in the type of results it can handle.

Expand All @@ -174,7 +255,7 @@ The class provides several methods for converting the fetched data into differen

The class also includes a `__repr__` method for a human-readable representation of the object, as well as the familiar Pydantic BaseModel methods like `model_dump()` and `model_json_schema()`.

## `Router` Class
## Router Class

The `Router` class in the OpenBB platform is responsible for managing and routing API requests. It uses the `APIRouter` from the FastAPI library to handle routing.

Expand Down Expand Up @@ -272,7 +353,9 @@ AVEquityHistoricalData(date=2023-11-03 00:00:00, open=174.24, high=176.82, low=1

> The `AVEquityHistoricalData` class, is a child class of the `Data` class.

Note how we've indexed to get only the first element of the `results` list (which represents a single row, if we want to think about it as a tabular output). This simply means that we are getting a `List` of `AVEquityHistoricalData` from the `obb.equity.price.historical` command. Or, we can also say that that's equivalent to `List[Data]`!
Note how we've indexed to get only the first element of the `results` list (which represents a single row, if we want to think about it as a tabular output).

This simply means that we are getting a `List` of `AVEquityHistoricalData` from the `obb.equity.price.historical` command. Or, we can also say that that's equivalent to `List[Data]`!

This is very powerful, as we can now apply any data processing command to the `results` list, without worrying about the underlying data structure.

Expand Down
38 changes: 38 additions & 0 deletions website/content/platform/developer_guide/command_coverage.mdx
Original file line number Diff line number Diff line change
@@ -0,0 +1,38 @@
---
title: Command Coverage
sidebar_position: 6
description: This page details the instructions for determining the command coverage provided by the installed extensions.
keywords:
- tutorial
- standardized output
- OBBject
- provider
- results
- warnings
- chart
- extra
- command coverage
---

## Commands and Provider Coverage

The installed commands and data providers are found under, `obb.coverage`.

```python
obb.coverage
```

```console
/coverage

providers
commands
command_model
command_schemas
```

`obb.coverage.providers` is a dictionary of the installed provider extensions, each with its own list of available commands.

`obb.coverage.commands` is a dictionary of commands, each with its own list of available providers for the data.

`obb.coverage.command_model` is a dictionary where the keys are the command paths and the values is a nested dictionary of QueryParams and Data models associated with that function.
Loading
Loading