New documentation site for Seldon Core v2 #5760

ramonpzg · 2024-07-16T07:01:04Z

The main purpose of this PR is to migrate our docs from readthedocs to GitBook.

Here are the changes I have made to transition the docs from one place to another.

Edits ✍️

Moved all documents out of source
Captions inside of mermaid diagrams have been moved to underneath the diagram as markdown.

Add Ons 🚀

SUMMARY.md file at the root of the docs directory to organize the docs.
I added a new directory called images to the docs directory and most images reside there now. I have added the correct path where necessary.
Referenced code via tags such as {literalinclude} have been replaced by the actual code these were referencing.
Mermaid diagram sections now start with mermaid as opposed to {mermaid}.
Block quotes such as {note} or {warning} you now need to surround block quotes with {% hint style="warning" %} and {% endhint %} (for more information see here).
Examples inside the docs directory now contain full documents rather than a reference. This includes:
- Huggingface speech to sentiment pipeline

Removed 🧹

Removed all files related to Sphinx and readthedocs.

Makefile
make.bat
requirements-docs.txt
index.md
conf.py
.gitignore - the files in it are now in the main .gitignore in the root directory of the repo
{toctree} at the end of most markdown files as gitbook provides this functionality
{literalinclude} and other references to different code files.
Full tutorials available in different directories should be edited from the docs as opposed to being references from the samples directory. This will help create a single place for tutorials and examples and minimize references to different files.

Admin 💼

All code references to full files now use GitHub Gist to stay up to date with master. Any suggestions on how to keep this in sync with branches for different versions of the docs, would be much appreciated.

Follow-Up Work (Different PR) 🤝

references to source of truth files

review-notebook-app · 2024-07-16T07:01:09Z

Check out this pull request on

See visual diffs & provide feedback on Jupyter Notebooks.

Powered by ReviewNB

CLAassistant · 2024-07-22T02:29:59Z

Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you all sign our Contributor License Agreement before we can accept your contribution.
1 out of 2 committers have signed the CLA.

✅ ramonpzg
❌ gitbook-bot
_{You have signed the CLA already but the status is still pending? Let us recheck it.}

lc525 · 2024-07-22T10:23:30Z

@ramonpzg I would like to form a view on the upgrade path to GitBook & timelines. At the moment, if I want to write some more Core 2 docs, would you recommend waiting for this PR to be merged first?

ramonpzg · 2024-07-22T13:23:33Z

@ramonpzg I would like to form a view on the upgrade path to GitBook & timelines. At the moment, if I want to write some more Core 2 docs, would you recommend waiting for this PR to be merged first?

@lc525 -- I will have the PR ready for review by sometime this week and would recommend waiting until the new docs have been merged. The reason is that since the docs directory structure has changed completely, rebasing with v2 to get the new changes might complicate things a bit. If these need to go out asap then no worries and move ahead with the changes. I can always look up the files that changed and update them manually on my branch.

lc525 · 2024-07-23T08:38:45Z

I will have the PR ready for review by sometime this week and would recommend waiting

@ramonpzg It's not that urgent, I can wait for this to be merged. Thank you for your work on this!

docs/README.md

docs/apis/internal/agent.md

docs/apis/internal/chainer.md

docs/apis/scheduler/README.md

docs/conversational_memory.ipynb

docs/getting-started/configuration.md

docs/pipelines/index.md

lc525

Reviewed with requested changes. Most I believe are minor, but I see the ability to include file contents (that was previously discussed) as very important.

…with enhancements

ramonpzg · 2024-08-27T05:12:12Z

I have created a new branch called v2-docs-master and pointed this PR towards it. Because this new branch was made with the V2 branch as a base, it is possible that there might be a few inconsistencies if the docs have changed in the last 2 weeks.

…anch

lc525

lgtm as a base, further changes to be built on top of this PR

To summarise our discussion, as next tasks:

@ramonpzg to investigate ways in which file references can point to the file corresponding to the exact release branch/tag rather than to v2
core 2 team to define changes required to the release process and test those

New format compatible with GItBook * moved docs out of the source directory and removed spnix-related files * APIs section completed * changing the configuration section in the getting started guide * getting started sectionc completed * rearranged models directory and enhanced different docs * added most images in the dos to the images directory * moved outliers and drift docs to its own file in the root directory * deleted servers directory and moved servers.md to the root directory with enhancements * deleted pipelines dir and moved pipelines.md to the root directory * deleted inference dir and moved inference.md to the root directory * deleted explainers dir and moved explainers.md to the root directory * deleted performance-tests dir and moved .md to the root directory * deleted experiments dir and moved .md to the root directory * updated about section to match gitbook's expected format * updated FAQs section to match gitbook's expected format * updated pandas query section with choice1.yaml * mostly moved and renamed files and directories * updated SUMMARY.md for GitBook * adding additional images * restructured development dir * restructured and reformatted examples dir to match GitBook's md flavor * added gitbook format to metrics dir * restructured k8s directory to match GitBooks expected md flavor * reformatted cli dir * typos and links fixed * typos and links fixed * tentative structured added to the root of the docs * fixed names in kubernetes section * GITBOOK-1: changed hard-coded reference to scheduler.proto * added reference to chainer.proto instead of hard-coded version * removed hard-coded references and added GitHub Gist pointing to v2 branch * fixed format and broken links feat(docs): adding a mention of per component labels and annotations to the docs (SeldonIO#5931) feat(docs): add documentation for HPA-based autoscaling (SeldonIO#5935) This describes a solution for scaling both Models and Servers based on HPA for the case of single-model serving. In the example described in the docs, the scaling is done based on Model RPS metrics fetched from Prometheus.

New format compatible with GItBook * moved docs out of the source directory and removed spnix-related files * APIs section completed * changing the configuration section in the getting started guide * getting started sectionc completed * rearranged models directory and enhanced different docs * added most images in the dos to the images directory * moved outliers and drift docs to its own file in the root directory * deleted servers directory and moved servers.md to the root directory with enhancements * deleted pipelines dir and moved pipelines.md to the root directory * deleted inference dir and moved inference.md to the root directory * deleted explainers dir and moved explainers.md to the root directory * deleted performance-tests dir and moved .md to the root directory * deleted experiments dir and moved .md to the root directory * updated about section to match gitbook's expected format * updated FAQs section to match gitbook's expected format * updated pandas query section with choice1.yaml * mostly moved and renamed files and directories * updated SUMMARY.md for GitBook * adding additional images * restructured development dir * restructured and reformatted examples dir to match GitBook's md flavor * added gitbook format to metrics dir * restructured k8s directory to match GitBooks expected md flavor * reformatted cli dir * typos and links fixed * typos and links fixed * tentative structured added to the root of the docs * fixed names in kubernetes section * GITBOOK-1: changed hard-coded reference to scheduler.proto * added reference to chainer.proto instead of hard-coded version * removed hard-coded references and added GitHub Gist pointing to v2 branch * fixed format and broken links --------- Co-authored-by: Ramon Perez <ramon.perez@seldon.io>

@Rajakavitha1

**PR Summary: New Documentation Site for Seldon Core v2 (#5760)** This PR introduces a comprehensive update to the documentation site for Seldon Core v2, aligning the format with GitBook requirements. Key changes include: - **File and Directory Restructuring**: Moved and renamed multiple files and directories to match GitBook's expected format, including APIs, models, examples, CLI, Kubernetes, and performance tests sections. - **Content Updates**: - Completed the APIs section and Getting Started guide. - Enhanced and reorganized the models directory and various other docs. - Outliers, drift, servers, pipelines, inference, explainers, and experiments docs moved to the root directory with improvements. - New documentation for HPA-based autoscaling for scaling both Models and Servers, referencing Model RPS metrics from Prometheus. - Added per-component labels and annotations in documentation. - **Images**: Consolidated images into a dedicated directory and updated links throughout the docs. - **Format Fixes**: Resolved broken links, corrected typos, and fixed references in Kubernetes and other sections. - **GitBook-Specific Updates**: - Updated `SUMMARY.md` for GitBook compatibility. - Reformatted the development, metrics, and K8s directories for GitBook’s markdown flavor. - Added GitHub Gist references for certain files (replacing hard-coded references). Co-authored by multiple contributors from the Seldon Core team. @Rajakavitha1 and @lc525

moved docs out of the source directory and removed spnix-related files

f39f911

ramonpzg requested review from sakoush and lc525 as code owners July 16, 2024 07:01

ramonpzg added Documentation do-not-merge/hold Developer Experience labels Jul 16, 2024

ramonpzg self-assigned this Jul 16, 2024

APIs section completed

669bbf1

lc525 added the v2 label Jul 16, 2024

changing the configuration section in the getting started guide

05321e8

getting started sectionc completed

4c0b628