docs: move Hugo docs into repo under docs/#5000
Conversation
|
/request-review @Yicong-Huang |
|
@Ma77Ball I will review it. |
|
@Ma77Ball can you update the PR description? it is a bit misleading. |
|
I updated it to exclude the part about maintaining consistency with the website, as that will be a separate pr. Please let me know if any other changes are needed. |
|
/unrequest-review @Yicong-Huang |
|
The PR looks good to me. @Yicong-Huang Can you verify? |
|
There is no way to review such a big Pr. As it is doc related, it won't affect prod code, I'm fine with merging it as it is. We can always fix small things later. But a question is how is this doc generated? How do we know if that's synced with codebase? |
Are your answers matching the questions in the PR template?
I don't think this makes sense? |
|
@Yicong-Huang I misunderstood the description issue. My bad, I fixed it now. Also, to address the other topic. It's synced with the codebase. I developed the website with Hugo, which uses Markdown (.md) files. I used the existing wiki from this repo and placed it in the docs folder under content. |
@Ma77Ball how about this question? Is there a test to verify the docs are synced with codebase? |
|
Verifying and syncing docs with the Texera website is a separate issue (#5001) I raised; should I raise that first, then this pr? Or if you mean it matches the wiki docs. In my understanding, the goal is to remove the wiki docs and keep only the website docs (at least after this PR is done #4435). @chenlica can comment on this. |
|
@Yicong-Huang here is a report to help with the review of what is included in the docs: Wiki sync status all 23 pagesComparison between Legend: ✅ in PR (present under ✅ In the PR (18)
❌ Not in the PR (5)
Totals
|
|
No, I mean syncing source code and the doc. Say in the future I open a new PR adding a new operator, but forget to add a doc section, is there a mechanism to alert me? Similarly, say I open a PR to change csv operator's parameters, is there a mechanism to alert me? We want to make sure the docs are in sync with the source code. To do that, usually we use source code to generate docs, and use CI to verify that the docs are generated from source. What we have now does not look like generated from source code. This will easily drift in the future. In fact, I don't know if the docs are aligned with what we have in source code, right now. |
|
That is a valid point. I can raise a new issue to discuss the details and open a PR to resolve this issue. Or I can raise it as part of this PR. |
Glad we agree on this. I can still approve and merge this PR, just to unblock the process, but we need to solve the sync issue between docs and source code eventually. For now, I will treat docs detached from source code. And new PRs will not need to modify docs until we sync them at one point. |
Yicong-Huang
left a comment
Yicong-Huang
left a comment
There was a problem hiding this comment.
Approved for a temporary status. Docs and source code are not synced/aligned atm. We will treat docs as a blob that is unrelated to source code for now.
|
The PR number 5000 is a big milestone! |
3 participants
What changes were proposed in this PR?
Adds the website documentation folder into the main repository under a new
docs/folder. The docs cover overview, getting started, tutorials, concepts, the operator reference, contribution guidelines, examples, and securityAny related issues, documentation, or discussions?
Closes: #4984
How was this PR tested?
copy pasted from and did a diff check against the Apache Texera website GitHub Repo
Was this PR authored or co-authored using generative AI tooling?
No