Documentation overhaul

[Secrus]

The documentation of Cleo is heavily outdated and requires some work. This issue will be the place to track PRs addressing points from the following checklist:

• Update sphinx, build system files, and clean up config files.
• Setup CI job to build Sphinx documentation on change in the docs/ directory
• Update documentation content:
  • Update guides for common use cases
  • Add or update doc comments in public API code
  • Emphasize supported environment variables (see #363)
• Setup CI job with cron for the deployment of docs from main branch and latest stable version

[adam-grant-hendry]

@Secrus Would you please consider adding #363 to your list?

[Secrus]

Sure! When we get to work on Cleo 3.0, I plan to go through the code file by file and document everything that is user-facing.

[adam-grant-hendry]

If you're comfortable with it, I'm happy to add things when I see them as I go through the docs in checklist format to this comment for your use later (may prove useful as insight from an end user's point of view).

Suggested Improvements

• Document environment variable usage for users ( #363 )
• Usage documentation references clikit under MODE in several sections, which is no longer a dependency (Replace with corresponding modules within cleo)
• Replace deprecated docstring syntax for Command description and signature in docs with cleo.helpers.option and cleo.helpers.argument syntax

[Secrus]

@adam-grant-hendry if you have time to do it, great. A lot of things will change, but overall I think end-user perspective will be useful.

• How to utilize corresponding class variables for Command description and signature items rather than implementing into docstring is not included (Relevant for those adhering to PEP 257 or Numpy/Google/Sphinx-style docstrings).

  Example
  e.g. This

  class GreetCommand(Command):
      """
      Greets someone
  
      greet
          {name? : Who do you want to greet?}
          {--y|yell : If set, the task will yell in uppercase letters}
      """
      def handle(self):
          ...

  Can also be achieved with:

  from cleo.helpers import option
  
  class GreetCommand(Command):
      name = 'greet'
      description = 'Greets someone'
      
      options: list[Option] = [
          option(
              'name',
              flag=False,
              value_required=False,
              description='Who do you want to greet?',
          ),
          option(
              'yell',
              short_name='y',
              description='If set, the task will yell in uppercase letters',
          )
      ]
      def handle(self):
          ...

This is no longer needed, since the docstring configuration option was removed with 2.0.

[adam-grant-hendry]

@Secrus Regarding the above, should I switch it to read:

"Replace deprecated docstring syntax for Command description and signature in docs with cleo.helpers.option and cleo.helpers.argument syntax"?

The documentation still instructs to use the deprecated docstring convention (not sure if you want to version the documentation and keep it for those still using cleo<2.0 with a note explaining it was deprecated in newer version though...If so, I'll also add to the list to version the documentation)

[Secrus]

@adam-grant-hendry The documentation is heavily outdated, so I don't think looking into it as a reference now is any good. If it references docstring config, it will be changed/removed.

[samyakkkk]

Hi @Secrus, would it be helpful users if we train an AI agent on the actual code of the repository + the issues instead?

It could help users get help as per the latest code syntax. plmk your thought - and I'm happy to volunteer to build one.

For context: I am also building a small tool for this problem.

[Secrus]

@samyakkkk if you feel a need for such a tool, you don't need my permission to make one. The code is on a permissive license, so feel free to use it. I don't plan on integrating any kind of AI tooling into the code though.