Skip to content

Commit

Permalink
[Docs] Refactor Docs Pages For Diataxis (#6315)
Browse files Browse the repository at this point in the history
* This change creates a PR

* start moving stuff around

* data_models/_category_.json

* reference/_category_.json

* moving some stuff around

* Introduction

* Documentation updates

* few broken links, clean up sidebar titles for how-to

* codespell

* quickstart - new provider extension

* add a comment

* map provider interface

* quickstart for new router extension

* [Docs] diataxis refactor refactor (#6425)

* Start refactor

* Edits

* [DOCS] Reorganize and edit. Fix sidebar navigation (#6445)

* Reorganize and edit. Fix sidebar navigation

* Fix broken linkages

* Edit

---------

Co-authored-by: Igor Radovanovic <[email protected]>

* Fix links

---------

Co-authored-by: Theodore Aptekarev <[email protected]>

* Fix broken links

* Reword CLA part in the Licensing FAQ

* change titles and order suggestion - cc @IgorWounds @piiq

---------

Co-authored-by: Igor Radovanovic <[email protected]>
Co-authored-by: James Maslek <[email protected]>
Co-authored-by: Theodore Aptekarev <[email protected]>
Co-authored-by: hjoaquim <[email protected]>
  • Loading branch information
5 people authored May 22, 2024
1 parent 7531e1d commit 3a8a71d
Show file tree
Hide file tree
Showing 77 changed files with 2,630 additions and 1,606 deletions.
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

0 comments on commit 3a8a71d

Please sign in to comment.