search

matthewgilbert / blp

Pythonic interface for Bloomberg Open API
Apache License 2.0
115 stars 25 forks source link

Enhancements to Quickstart Documentation #33

Closed avantgardeam closed 10 months ago

avantgardeam commented 10 months ago

Hello @matthewgilbert,

This is the PR in response to issue #31, focused on improving the quickstart documentation. Major changes include switching from Jupyter notebooks to Quarto for better features like a table of contents. Additionally, I also reorganized the sections for clearer structure.

If you think these changes don't align with the project goals, feel free to reject this PR. If this happens, I'll add just the BQL and EQS examples as initially planned.

The committed HTML is ready for deployment on platforms like GitHub Pages.

Thank you for considering this PR!

matthewgilbert commented 10 months ago

Thanks @avantgardeam , this looks great! More than happy to merge the PR. I've heard good things about Quarto so happy to switch, the formatting looks better and I appreciate the improved organizational layout. This in particular is a great addition :smile:

We highly advise thoroughly reviewing the BLPAPI Core Developer Guide when developing your Bloomberg Queries. This guide is essential for understanding function parameters, request options, overrides, error messages, and troubleshooting methods.

A couple questions

  1. Is the quickstart.py file here just to have a python executable version of docs in case users want to run? Or does this serve some other purpose in Quarto?
  2. Would you happen to have a snippet of how you rendered the html? Is the workflow here that the quickstart.qmd file is used to generate both the quickstart.py file and the quickstart.html file?
avantgardeam commented 10 months ago

Thanks @avantgardeam , this looks great! More than happy to merge the PR. I've heard good things about Quarto so happy to switch, the formatting looks better and I appreciate the improved organizational layout. This in particular is a great addition 😄

We highly advise thoroughly reviewing the BLPAPI Core Developer Guide when developing your Bloomberg Queries. This guide is essential for understanding function parameters, request options, overrides, error messages, and troubleshooting methods.

A couple questions

  1. Is the quickstart.py file here just to have a python executable version of docs in case users want to run? Or does this serve some other purpose in Quarto?
  2. Would you happen to have a snippet of how you rendered the html? Is the workflow here that the quickstart.qmd file is used to generate both the quickstart.py file and the quickstart.html file?

I'm glad you appreciated the updates! Here are the answers to your questions:

  1. The quickstart.py file serves primarily as a runnable version of the documentation. While it was included to maintain consistency with the previous version, it's not essential and can be removed without impacting the documentation.
  2. Generating the HTML file from quickstart.qmd is straightforward. Simply execute quarto render quickstart.qmd in the terminal. The quickstart.py file was created by converting a Quarto notebook to a Jupyter notebook, and then to .py. However, as mentioned, its removal won't affect anything.