Doc site edits

[apiology]

https://solargraph.org/guides

replace first paragraph:

Solargraph is a Ruby language server and suite of static analysis tools. The language server provides intellisense, autocompletion, diagnostics, and other language features for editors and IDEs with language client capabilities. The static analysis tools check code for type safety using types from RBS and YARD.

• Ruby 2.1.0 or higher -> Ruby 3.0 or higher
• Replace emacs link with https://johnhame.link/posts/tweaking-emacs-for-ruby-development-in-2023/#lsp

https://solargraph.org/guides/getting-started

• Drop "Get the Core Documentation"
• Add in its place "Pull in outside types":

"Solargraph automatically generates type information from installed gems, based on the YARD or RBS information inside the gem.

To ensure you have types for gems which contain neither RBS nor YARD information, use gem_rbs_collection to install a community-supported set of types:

bundle exec rbs collection init
bundle exec rbs collection install

You can eagerly cache this type information with the solargraph gems command.

Once installed, you can also insert your own local overrides and definitions in RBS in a directory configured in the rbs_collection.yaml that the above commands create.

https://solargraph.org/guides/configuration

See my suggestions in #1126

https://solargraph.org/guides/performance

GTG

https://solargraph.org/guides/troubleshooting

• Replace "The most common reason for a gem to be missing from your intellisense is missing YARD documentation. You can generate the documentation by running yard gems on the command line." with

"The most common reason for a gem to be missing from your intellisense is missing type documentation. Not every gem has full type information available, but this is a good sequence of steps to make sure you have whatever information you can get, even if it's only method and argument names.

Note: If your gem or Solargraph itself is not in your bundle, drop all of the 'bundle exec' prefixes below.

1. See if Solargraph has the information already:

   bundle exec solargraph pin SomeModule::SomeClass#some_method

   If the output shows type information for your method, restart your editor to make sure the LSP is pulling the latest and greatest information.

2. If nothing popped up or it lacks types, ensure your RBS collection is up to date with community type information from the outside world for your bundle:

   bundle exec rbs collection init 
   bundle exec rbs collection install
   bundle exec rbs collection update
   

3. Now tell Solargraph to digest the RBS collection information along with YARD or RBS information in the gem itself:

   bundle exec solargraph gems GEM_NAME_HERE
   

4. Once done, try again to look for your example method:

   bundle exec solargraph pin SomeModule::SomeClass#some_method
   

   If this now shows type information for your method, restart your editor and try again.

5. If you only see method signatures without types, double check that you have applicable plugins - e.g., solargraph-rails. If you do already, it's likely that your gem doesn't have type information at all. Consider writing type information yourself in the RBS language and contributing it back to the gem, or the gem_rbs_collection repo if that's not an option. You can test it locally by configuring a directory for it in your rbs_collection.yaml file."

• Replace "Run bundle exec yard gems." with: "Install your RBS collection information as documented above, then run bundle exec solargraph gems.

https://solargraph.org/guides/scanning-workspaces

GTG

https://solargraph.org/guides/yard

• Pull in generic tag docs from README.md in yard-solargraph

https://solargraph.org/guides/rails

The solargraph-rails plugin is recommended for enhancing Solargraph’s capabilities in Rails projects. It extends Solargraph to handle many of the dynamic aspects of Rails. This includes ActiveRecord column types, finders and associations, type support for various DSLs, and more!

https://solargraph.org/guides/type-checking

• Replace "NOTE: Type checking is a work in progress." with "NOTE: We are eager for feedback on Solargraph's typechecking functionality."

• Replace "Solargraph provides a type checker that can idenfity problems like invalid tags, unrecognized methods, and mismatched types." with "Solargraph provides a type checker that can identify problems like invalid tags, unrecognized methods, mismatched types, and potentially-nil variables based on the YARD tags you supply in your code".

• Replace "solargraph ./path/to/file.rb" with "solargraph typecheck ./path/to/file.rb"

• Add as new paragraph at end of "Type Checking Rules":
  "You can use tools like overcommit to ensure that new and changed code are typechecked at your target level"

• Replace "The checker verifies that all tag types, e.g., @return [String], can be resolved. Classes, modules, duck types (e.g., [#to_s]), and special YARD types like [Boolean] and [void] are all valid." with The checker verifies that all tag types, e.g., @return [String], can be resolved. Classes, modules, duck types (e.g., [#to_s]), generic types (e.g., Set<String> and Hash{Symbol => Integer}) and special YARD types like [Boolean] and [void] are all valid.

• Add to "The Strict Level" and "The Strong Level": * Validate constants

• Add to "The Strong Level": * Ensure nil checks by validating union use

https://solargraph.org/guides/language-server

• "Diagnostics (linting)" -> "Diagnostics (linting and type checking)"
• Replace text in "Working Implementations" with "See Supported Editors for a list of integrations of this LSP.

https://solargraph.org/guides/type-detection

• Add a section 'nil checking' as a section under 'Inference'

  Solargraph uses a static-analysis technique called "[flow-sensitive typing](https://en.wikipedia.org/wiki/Flow-sensitive_typing)" to help determine whether a variable can be nil at any given point.  
  
  Example:
  
  ```
  # @param foo [String, nil]
  #
  # @return [String]
  def bar(foo)
    if foo.nil? # foo is type String, nil
       return "default" # foo is type nil
    else
       return foo # foo is type String
    end
  end
  ```
  
  If you use the 'strong' type-checking level, you'll then see type checking errors based on this information:
  
  ```
  # @param baz [String, nil]
  #
  # @return [String]
  def quux(baz)
    baz.upcase # ERROR: Unresolved call to upcase on String, nil
  end
  ```
  

https://solargraph.org/guides/plugins

No changes

https://solargraph.org/guides/code-examples

No changes

https://solargraph.org/demo

Updating the Solargraph version here would be lovely if straightforward