The great documentation update

[Mpdreamz]

We made great strides in 2.x having our documentation generated from actual code using roslyn to visit certain tests.

This issue serves as an aggregate for remaining documentation issues so we can track it in one issue and make one big last swoop to get it into its final shape.

• Our docs are flattened on elastic.co site. We closely mimic elasticsearch's documentation tree but our generator loses much of this information. We need to be sure the documentation maintains the same tree in the generated asciidoc output.
• We do not generate documentation for the API tests yet. The idea is to visit all Usage and Crud tests and based on a consistent hash pick one of the 4 ways (sync/async and inititalizer/fluent) (was (Document async options #2239).
• similarly all our analysis tests should end up in the documentation (Documentation for Analysis components #1991)
• For various reasons we would like to embedd tables (BenchMarkDotNet output for instance) our AsciiDoc parser does not handle this yet (Support Table elements russcam/asciidocnet#2)
• Revisit the flow of our Core docs (NEST 2.X Documentation Lacks a "Core" Section #2069)
• Documentation: Clarify how a Connection Pool works and that its not responsible for the actual TCP connection pooling (Documentation: Clarify how a Connection Pool works #2260)
• Write a dedicated section on how to see what the client is doing (fiddler, logging, tracing, debuginformation, audits) (Ability to display the query that is being executed in a log message / output window.. #864 Document how to hook Log4Net, NLog, Serilog into NEST/Elasticsearch.NET #865)
• Add Compatibility Matrix from README to docs Add Compatibility Matrix from README to docs #2243
• Document Search Template Document Search Template API usage #2729
• Provide better context in .doc.cs cases see Suggestion: Regarding documentation of Elastic Search #3183
• Document Suggesters (Update suggest-usage.asciidoc #2928)
• Improve Parent/Child documentation (Routing method not available? #3542)

[russcam]

Here's the rough Table of Contents for the new documentation

NEST Documentation

• Introduction

• Breaking Changes

  • Elasticsearch.Net breaking changes
  • NEST breaking changes

• Elasticsearch.Net - Low level client

  • Getting started
    • Installing
    • Connecting
    • Calling an API
    • Providing a request body

• NEST - High level client

  • Getting started
    • Installing
    • Connecting
    • Indexing
    • Searching
    • Aggregations
  • Connecting
    • Configuration Options
    • Connection pools
    • Configuring SSL
    • Modifying the default connection
  • Serialization
    • Changing serializers
    • Modifying the default serializer
  • Mapping
    • Automapping
      • Inferred / Mapping from POCOs
      • Attributes
      • Fluent
      • Visitor pattern
    • Multi-fields
  • Analysis
    • Writing analyzers
    • Testing Analyzers
      • Analyze API
      • Explain API
  • Working with documents
    • Indexing
      • Single Document
      • Bulk
      • Ingest Node
    • Retrieving
    • Updating
    • Deleting
  • Search
    • Writing queries
      • Full-text
      • Term level
    • Compound queries
    • Conditionless queries
    • Single search
    • Multi search
    • Source filtering
    • Sorting
    • Highlighting
    • Covariant search results
    • Suggesters
  • Aggregations
    • Writing aggregations
    • Handling aggregation results
    • Sub aggregations
  • Common types
    • Indices
    • Types
    • Fields
    • Time
    • Distance
    • DateMath
  • X-Pack plugins
    • Security
    • Alerting
    • Graph
  • Debugging and Troubleshooting
    • Audit Trail and DebugInformation
    • Logging requests and responses

/* Reference */

• Document APIs
• Analysis
• Mapping
• Search APIs
  • Search Parameters
• Query DSL
  • Full text
  • Term level
  • Compound
  • Joining
  • Geo
  • Specialized
  • Span
  • Nest specific
• Aggregations
  • Metric
  • Bucket
  • Pipeline
  • Matrix

[stevejgordon]

It might just be a personal thing but I find it frustrating that many of the public classes and methods do not seem to have XML comments against them explaining their usage / what they do. We exploring the public API I find this useful to learn my way around it. I find myself having to try and find the info in documentation or as I've just done, by pulling source.

Are their plans to include more XML comments?

For example, I was trying to work out how the TypeName parameter of BulkRequest should be used and have resorted to starting to read the source this morning.

[Mpdreamz]

@stevejgordon thanks for voicing your concerns around this, we absolutely started doing this more and more. I'm personally allergic to generated xmldocs so I rather opt for none over "Sets TypeName".

That said our goal is to definitely retroactively go over our public API to add them in.

[schmitch]

btw.

Working with documents

    Indexing
        Single Document
        Bulk
        Ingest Node
    Retrieving
    Updating
    Deleting

is completly missing

[russcam]

Thanks for the bump, @schmitch!

There's a few documentation sections in the table of contents that have not yet been implemented. We've kept the issue open because we would like to implement them, but other work has taken priority; we're looking at improving the performance of the client at the moment.

We would be super happy to accept a contribution for documentation, if it's something you'd be interested in?

[Trisped]

Not sure if this is the correct place, but Mapping an Index name for a .NET type needs some work.

The first code sample is the same as the second sample and does not exemplify MapDefaultTypeIndices as indicated by the line describing what should be in the example.

At the time of this writing, the current documentation was version 6.0.

[Trisped]

Also, I have run into a few places in the intelisense documenation where the links are broken. For example, the DeleteIndexAsync method on Nest.ElasticClient states:

The delete index API allows to delete an existing index.
http://www.elasticsearch.org/guide/en/elasticsearch/reference/current/indices-delete-index.html

The link will work if you replace http://www.elasticsearch.org with https://www.elastic.co.

@russcam Please confirm that this is the correct place to log this and the above issue.

[russcam]

@Trisped Thanks for reporting. It's probably best to open new, separate issues for each of these

[aeslinger0]

This issue has been open for three years and still no example on how to update a document with Nest?

[russcam]

There are plenty of examples in the source and out on the web, but not in the docs as yet. We're currently working on bringing parity with Elasticsearch 7.4 to the client, but after this there may be an opportunity to address this.

[stevejgordon]

Closing due to age/inactivity. Please let us know if this issue is still a relevant priority for your usage?