Legacy documentation

[demurgos]

Hi,
We are currently in the process of migrating the documentation for request version 1 ("legacy") from the library's README to the website. The goal of this migration is improve the documentation thanks to the possibility to structure and expand the current documentation: we have a whole website dedicated to documentation instead of a single file.

Objectives

Here are some concrete points I would like to focus on during the migration:

• API completeness: Dedicate a whole section for the API and make it exhaustive. request's API is much is larger than just the supported options. The module exports many functions (cookie, defaults, ...) and the returned values are often complex objects. Any object publicly accessible should be documented: the API documentation's completeness is a crucial for the guarantees offered by the semantic versioning of request.
• Examples: The original documentation has examples built around use cases (streaming, forms, etc.). These are good and we should keep them, but the API also needs examples. Ideally, each function or option should provide a few usage examples. These examples should be commented and runnable (do not assume any implicit context, most of times it just means that you should add the module importation).
• Types: Types provide information about the allowed values. Even if JavaScript is dynamically typed, having a clear definition of the type of a variable can help to complete the eventual vagueness in the english description (like the examples mentioned above). Since there is no standard syntax for this in Javascript, you can use some pseudo-code notation as long as it's clear. A recommended source of inspiration might be Typescript's notation. Try to render types as links to their description (see Node's documentation where types are clickable).
• Data relations: request defines some complex relations between it's objects. The function's signature can change the required options (.uri can be either provided as a function argument or as an option), there are some aliases, some flags control the effect other options (.useQuerystring), etc. In my opinion, these relations should be at least mentioned in the description of every implied object.
• External references: Every time request mentions an external resource, there should be a link. This link should be a permalink and ideally, you'd check that the target is archived on archive.org.

Related issues

• Create directory structure and entries in the summary
• Import the original documentation
• Add entries for all the public objects
• Add description for each public object
• Add examples for the module's main functions
• Update the main options documentation
• Check the features pages
• Fix the broken links (mainly around the the features pages ?), ensure that there is an archived version for the links
• Document missing types
• Solve TODOs remaining in the documentation
• TODO: Expand this list, open dedicated tickets to track progress, create a milestone ?

Contributing

While the legacy documentation is not ready to be published, work happens on the legacy-doc branch.
Make sure to choose this branch when submitting a Pull Request (PR).

Do not hesitate to comment here for general remarks or questions about the migration of the legacy documentation.

Previous discussions

• Legacy documentation #3

[demurgos]

@simov
Could you clarify how you envision the relation between the master and legacy-doc branches ? Here are the three possible ways I see:

• Merge legacy-doc right now and delete it, push the new changes to master. (Changes go live as quickly as possible)
• Push all the new changes (related to the legacy doc) to legacy-doc and wait until it's stable enough, then merge it to master and delete it, the next changes go to master. (Changes go live once the whole legacy documentation is migrated)
• Push new changes to legacy-doc but also perform regularly merges from legacy-doc to master while keeping legacy-doc. The changes continue to go to legacy-doc until the final merge to master after which we delete legacy-doc. (Keep legacy-doc until the end of the migration, but push changes to live from time to time)

[simov]

Once we have at least all navigation/summary links figured out we can merge to master, effectively publishing the docs to gitbook. Don't worry about missing stuff and TODO's here and there.

Good job on this issue 👍