feat(AL-885): Revamped documentation

[MiguelTapTagshelf]

Jira Ticket: AL-885

Changes

• README Updated: - The README provides a brief overview of the library and its key features.
  - Includes links to more detailed documentation sections.

• Authentication Methods Documented:
  Clear documentation on the three login methodologies.

• File Upload Documentation extended:
  The file upload process is documented in a step-by-step guide with corresponding code examples.

• Real-Time Engine Usage:
  Documentation includes instructions on initializing and using the real-time engine.

Code Examples and Clarity:

• All documentation has relevant code examples that are tested and verified to work.

• Language used in the documentation is clear, concise, and free of jargon where possible.

• Community Contribution Guidelines:
  There is a section encouraging and guiding community contributions, including detailed steps for contributing.

[rroa]

General Feedback

Overall, the documentation needs significant improvements to enhance clarity and cohesion. Currently, it feels disjointed, and the steps are hard to follow. It's crucial to ensure that each step is connected and that the examples are presented as cohesive programs rather than isolated snippets within the Python interpreter.

I had left the following feedback to @Edu-B in AL-887

Here are the key questions the documentation should address:

1. Why do I want to use Alfred?

   • Clearly explain the purpose and benefits of using Alfred.

2. Where do I start so I can use this library to access Alfred?

   • Provide a clear starting point, including installation and initial configuration instructions.

3. How do I feed Alfred with information so it does its magic for me?

   • Offer detailed steps on how to send data to Alfred, ensuring the process is easy to understand and follow.

4. How do I know it's done?

   • Explain how to check the status of data processing, including any indicators or notifications that inform users of completion.

5. How do I see results?

   • Describe how to retrieve and view the results after Alfred has processed the data.

Additionally, there's information missing related to real-time notifications. This PR/Jira issue was previously blocked due to Marlyn working on the feature, but as I understand, the feature is now complete.

Code Formatting Tips

To improve the readability and professionalism of the code examples, please follow these formatting guidelines:

1. Avoid single-line dictionaries: Use multi-line formatting for dictionaries to enhance readability.

   # Good example
   data = {
       "key1": "value1",
       "key2": "value2",
       "key3": "value3"
   }
   
   # Bad example
   data = {"key1": "value1", "key2": "value2", "key3": "value3"}

2. Use consistent indentation: Ensure all code blocks use the same level of indentation, preferably 4 spaces.

   # Good example
   def example_function():
       data = {
           "key1": "value1",
           "key2": "value2"
       }
       return data
   
   # Bad example
   def example_function():
     data = {
       "key1": "value1",
       "key2": "value2"
     }
     return data

3. Provide complete code examples: Each example should be a self-contained, runnable script, demonstrating the full process from start to finish.

   # Complete example
   import alfred
   
   # Authenticate
   alfred.authenticate('your_api_key')
   
   # Send data
   data = {
       "key1": "value1",
       "key2": "value2"
   }
   response = alfred.send_data(data)
   
   # Check status
   status = alfred.check_status(response['task_id'])
   
   # Fetch results
   if status == 'completed':
       results = alfred.get_results(response['task_id'])
       print(results)

4. Comment your code: Add comments to explain the purpose of each section and key lines of code.

   # Authenticate with Alfred
   alfred.authenticate('your_api_key')
   
   # Data to be sent to Alfred
   data = {
       "key1": "value1",
       "key2": "value2"
   }
   
   # Send data and get the response
   response = alfred.send_data(data)

5. Use meaningful variable names: Ensure that variable names are descriptive and meaningful.

   # Good example
   user_data = {
       "username": "johndoe",
       "email": "[email protected]"
   }
   
   # Bad example
   x = {
       "u": "johndoe",
       "e": "[email protected]"
   }

These tips will help in creating a more professional and user-friendly documentation that is easier to follow and understand.

[rroa]

Please follow up feedback comments and update.

[rroa]

It's pypi not pypy

[rroa]

Why would I want to create a session to get started? I think that a call to who am I is the proper way to "confirm" you are authenticated.

[rroa]

When showing dictionaries or JSON results, please "prettify" them rather than placing them in a single line.