Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Automation: Main Next Integrate #11798

Merged
merged 6 commits into from Sep 2, 2022
Merged

Automation: Main Next Integrate #11798

merged 6 commits into from Sep 2, 2022

Conversation

github-actions[bot]
Copy link
Contributor

@github-actions github-actions bot commented Sep 2, 2022

Main-next integrate PR

The aim of this pull request is to sync main and next branch. The expectation from the assignee is as follows:

  • Acknowledge the pull request by adding a comment -- "Actively working on it".
  • Resolve any merge conflicts between this branch and next (and push the resolution to this branch). Merge next into this branch if needed. Do NOT rebase or squash this branch: its history must be preserved.
  • Ensure CI is passing for this PR, fixing any issues. Please don't look into resolving Real service e2e test and Stress test failures as they are non-required CI failures.
  • Once the PR is ready for merge, please add a comment @mentioning the reviewers to get this PR merged in. Thank you!!

For more information about how to resolve merge conflicts and CI failures, visit [this wiki page]
(https://github.com/microsoft/FluidFramework/wiki/Main-next-Automation).

CraigMacomber and others added 5 commits August 30, 2022 15:55
@CraigMacomber
Document Trailing Ops Compatibility (#11685)
8a4f5c9
@sonalivdeshpande
Add build:full as part of new build tools CI pipeline (#11575)
8203620
@Josmithr @tylerbutler
Add api-markdown-documenter package to replace our external api-docum…
25394b6 
…enter fork (#11542)

Adds new package: `@fluid-tools/api-markdown-documenter` - a wrapper around [API-Documenter](https://github.com/microsoft/rushstack/tree/main/apps/api-documenter) which offers a programmatic API surface for generating API documentation from an API report generated by [API-Extractor](https://api-extractor.com/).

## Goal

The purpose of this library is to process the reports generated by API-Extractor and generate a suite Markdown-formatted API documentation from them. Generally, this is accomplished by using API-Documenter directly, but that package has a number of serious limitations:

- It prescribes a specific documentation suite layout, and one that was crafted for use with DocFX specifically.
    - We are not using DocFX, and the DocFX format does not work well with our website generation system (Hugo).
- It generates a separate file for **each API item**.
    - This ends up being a massive list of files, and requires a lot of needless cross-page navigation when reading the documentation.
- It exposes only a single, CLI entrypoint, which takes in a list of API reports and generates a set of files.
    - This does not offer much in the way of flexibility, and means we are limited with regards to how we use the generated content.

This library aims to solve these problems by exposing an API surface with the following primary goals:

- Support programmatic usage
    - Allows consumers to do more with the generated content other than simply writing it unmodified to disk. By offering an API that returns a description of documentation content, consumers may choose to embed the content in other document files, transform the contents to inject system-specific (e.g. Hugo) front-matter before writing content to disk, etc.
- Highly extensible / configurable
    - Offers flexibility around file / directory layout, content-type-wise rendering policy, etc. (with a suite of default policies and rendering helpers).

## Current Status

V1 adds the general logic for generating markdown documentation with some level of configurability. It does not yet generate documentation in visual parity with our existing [API-Documenter fork](https://github.com/tylerbutler/custom-api-documenter/tree/dev) (though it is pretty close). Such parity (aside from some visual and hierarchical improvements over our existing fork) will be added in future PRs.

The main entry-points to the library are in `MarkdownDocumenter.ts`.

Extensibility options are exposed via config types declared in `Policies.ts` and `RenderingPolicy.ts`.

For sample rendering output, see the contents of `src/test/snapshots`. It is the test output for a sample test-suite copied over from our API-Documenter fork.

Note that the package currently does not have a CLI entry-point. I'm not sure we really need one. I see this being invoked programmatically so we can inject Hugo frontmatter, etc. dynamically. This can always be re-evaluated in the future though, if we think one would be valuable.

## Open Questions

1. Where does this live? This really isn't Fluid-related, it's just a tool we intend to maintain / use. Should this be in its own repo? In a repo with other library packages we maintain and use, but aren't actually Fluid-specific?

## Next steps

This PR will merge the package in as a "private" package. Further work will need to be done before making it public and consuming it in the website code (/docs). My intention is to tackle these as subsequent PRs

- Verify Hugo compatibility in this website code
- Update rendering to have style-wise parity with the current implementation

And, of course, eventually replace our use of the existing API-Documenter fork with the new package.

For reference, I have a draft PR up with the changes (relative to this branch) to start using the new package in our docs build: Josmithr#1

## Long-Term Goals

Longer term, we wish to expand on this library to be even more flexible / configurable and to rely on API-Documenter-specific concepts less. The intention is to model this library in terms of Abstract Syntax Trees (ASTs), using [unist](https://github.com/syntax-tree/unist) and [mdast](https://github.com/syntax-tree/mdast) to offer consumers a more granular surface for generating / modifying generated API docs contents.

Co-authored-by: Justin Myhres <Justin.Myhres@microsoft.com>
Co-authored-by: Tyler Butler <tyler@tylerbutler.com>
@sonalivdeshpande
Few more nits in workflow (#11740)
bdb1802
@connorskees
fix(sequence merge-tree): more robustly handle rebasing interval ops (#…
179502b 
…11672)
@github-actions github-actions bot requested review from msfluid-bot and a team as code owners September 2, 2022 17:40
@github-actions github-actions bot added area: build Build related issues area: dds Issues related to distributed data structures area: dds: sharedstring public api change Changes to a public API labels Sep 2, 2022
@github-actions github-actions bot added the base: next PRs targeted against next branch label Sep 2, 2022
@msfluid-bot
Copy link
Collaborator

Could not find a usable baseline build with search starting at CI 179502b

Generated by 🚫 dangerJS against ea6a105

@sonalivdeshpande sonalivdeshpande merged commit 5fd40e5 into next Sep 2, 2022
@sonalivdeshpande sonalivdeshpande deleted the main-next-179502b45712b92c9ae5e833f4b28182ba74b7ef branch September 2, 2022 20:40
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@sonalivdeshpande sonalivdeshpande sonalivdeshpande approved these changes

@msfluid-bot msfluid-bot Awaiting requested review from msfluid-bot msfluid-bot is a code owner

@tylerbutler tylerbutler Awaiting requested review from tylerbutler

Assignees

@connorskees connorskees

Labels
area: build Build related issues area: dds: sharedstring area: dds Issues related to distributed data structures base: next PRs targeted against next branch community-contribution do-not-squash-merge main-next-integrate public api change Changes to a public API
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.

None yet
6 participants
@msfluid-bot @sonalivdeshpande @tylerbutler @connorskees @CraigMacomber @Josmithr