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

Restructure documentation. Now the documentation has installation, administration, usage, development, contributing the 5 main parts #23629

Merged
merged 10 commits into from
Mar 23, 2023

Conversation

lunny
Copy link
Member

@lunny lunny commented Mar 22, 2023

  • Installation: includes how to install Gitea and related other tools, also includes upgrade Gitea
  • Administration: includes how to configure Gitea, customize Gitea and manage Gitea instance out of Gitea admin UI
  • Usage: includes how to use Gitea's functionalities. A sub documentation is about packages, in future we could also include CI/CD and others.
  • Development: includes how to integrate with Gitea's API, how to develop new features within Gitea
  • Contributing: includes how to contribute code to Gitea repositories.

After this is merged, I think we can have a sub-documentation of Usage part named Actions to describe how to use Gitea actions

…minister, usage, develop, contribute the 5 main parts
@lunny lunny added type/docs This PR mainly updates/creates documentation pr/wip This PR is not ready for review labels Mar 22, 2023
docs/Makefile Outdated Show resolved Hide resolved
@GiteaBot GiteaBot added the lgtm/need 2 This PR needs two approvals by maintainers to be considered for merging. label Mar 22, 2023
@lunny lunny removed the pr/wip This PR is not ready for review label Mar 22, 2023
Copy link
Member

@yardenshoham yardenshoham left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

image
Comparison seems out of place

@delvh
Copy link
Member

delvh commented Mar 22, 2023

Hmm, isn't Installation and Administer basically the same thing?
Could we perhaps combine them under Setup?

@lunny
Copy link
Member Author

lunny commented Mar 22, 2023

Hmm, isn't Installation and Administer basically the same thing? Could we perhaps combine them under Setup?

I think you are right. But I move them as standalone documentation according to most people's habits.

@lunny
Copy link
Member Author

lunny commented Mar 22, 2023

image Comparison seems out of place

Looks like we need to change the theme about the style.

@wxiaoguang
Copy link
Contributor

wxiaoguang commented Mar 22, 2023

I think separating Installation from Administer is more friendly for new users.

Makefile Outdated Show resolved Hide resolved
docs/content/doc/packages/rubygems.en-us.md Outdated Show resolved Hide resolved
docs/content/doc/pacakges.md Outdated Show resolved Hide resolved
@delvh
Copy link
Member

delvh commented Mar 22, 2023

By the way, should we backport this PR to 1.19?
As we are moving towards versioned docs, it would also be nice there…

@wxiaoguang
Copy link
Contributor

And I also have a (similar) question, what's the progress of Versioned Document? Does this change work with Versioned Document (how does it work with 1.19)?

@lunny
Copy link
Member Author

lunny commented Mar 22, 2023

And I also have a (similar) question, what's the progress of Versioned Document? Does this change work with Versioned Document (how does it work with 1.19)?

The versioned document repository is https://gitea.com/gitea/gitea-docusaurus . I think after this merged, it needs some adjustments. @techknowlogick

@lunny lunny added the outdated/backport/v1.19 This PR should be backported to Gitea 1.19 label Mar 22, 2023
@lunny
Copy link
Member Author

lunny commented Mar 22, 2023

Looks like there is no new feature merged after 1.19 branch created, so I think yes, we can backport this to 1.19 to make versioned documentation easier.

@@ -817,7 +818,7 @@ release-docs: | $(DIST_DIRS) docs
.PHONY: docs
docs:
@hash hugo > /dev/null 2>&1; if [ $$? -ne 0 ]; then \
curl -sL https://github.com/gohugoio/hugo/releases/download/v0.111.3/hugo_0.111.3_Linux-64bit.tar.gz | tar zxf - -C /tmp && mv /tmp/hugo /usr/bin/hugo && chmod +x /usr/bin/hugo; \
curl -sL https://github.com/gohugoio/hugo/releases/download/v$(HUGO_VERSION)/hugo_$(HUGO_VERSION)_Linux-64bit.tar.gz | tar zxf - -C /tmp && mv /tmp/hugo /usr/bin/hugo && chmod +x /usr/bin/hugo; \
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This will break Gitpod. It's fine, I guess I will fix it after this is merged

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actually, this variable isn't used anywhere else so I'd rather just keeping the version hardcoded here

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Since I have changed that and if it's equal. Maybe just leave it.

@GiteaBot GiteaBot added lgtm/need 1 This PR needs approval from one additional maintainer to be merged. and removed lgtm/need 2 This PR needs two approvals by maintainers to be considered for merging. labels Mar 22, 2023
@jolheiser
Copy link
Member

We should find a spot for comparison before merging this.

Either by changing the theme, adding it to the index, or adding it to another section.

@delvh
Copy link
Member

delvh commented Mar 22, 2023

Usage/Installation?

Copy link
Member

@jolheiser jolheiser left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

As well, I think "Help" should be moved back to the top imo

docs/content/doc/usage/secrets.en-us.md Outdated Show resolved Hide resolved
docs/content/doc/usage/secrets.en-us.md Outdated Show resolved Hide resolved
@lunny
Copy link
Member Author

lunny commented Mar 23, 2023

I think it should be Contributing but Contibution

@yardenshoham
Copy link
Member

I agree, let's do:

Installation
Administration
Usage
Development
Contributing

@lunny
Copy link
Member Author

lunny commented Mar 23, 2023

As well, I think "Help" should be moved back to the top imo

I have a different thought about moving help in the last. The FAQ should be read after users read all the documentation but with no answer. And support chat channel should also be given when users cannot find the answer from the documentation. They are not encouraged to ask in the chatroom before they read the documentation carefully.

@lunny lunny changed the title Restructure documentation. Now the documentation has installation, administer, usage, develop, contribute the 5 main parts Restructure documentation. Now the documentation has installation, administration, usage, development, contributing the 5 main parts Mar 23, 2023
@GiteaBot GiteaBot added lgtm/done This PR has enough approvals to get merged. There are no important open reservations anymore. and removed lgtm/need 1 This PR needs approval from one additional maintainer to be merged. labels Mar 23, 2023
@lunny lunny merged commit e8433b7 into go-gitea:main Mar 23, 2023
@lunny lunny deleted the lunny/restructure_docs branch March 23, 2023 15:18
@GiteaBot
Copy link
Collaborator

I was unable to create a backport for 1.19, please send one manually. 🍵

@GiteaBot GiteaBot added the backport/manual No power to the bots! Create your backport yourself! label Mar 23, 2023
@lunny lunny added the backport/done All backports for this PR have been created label Mar 23, 2023
jolheiser pushed a commit that referenced this pull request Mar 23, 2023
… -> administration (#23662)

backport #23629 

To make versioned documentation less surprising, 1.19 should have the
same technology.
zjjhot added a commit to zjjhot/gitea that referenced this pull request Mar 24, 2023
* upstream/main:
  Fix incorrect `HookEventType` of pull request review comments (go-gitea#23650)
  [skip ci] Updated translations via Crowdin
  Fix codeblocks in the cheat sheet (go-gitea#23664)
  Drop migration for ForeignReference (go-gitea#23605)
  Fix new issue/pull request btn margin when it is next to sort (go-gitea#23647)
  A tool to help to backport locales, changes source strings to fix other broken translations (go-gitea#23633)
  Fix incorrect `show-modal` and `show-panel` class (go-gitea#23660)
  Restructure documentation. Now the documentation has installation, administration, usage, development, contributing the 5 main parts (go-gitea#23629)
  Check LFS/Packages settings in dump and doctor command (go-gitea#23631)
  Use a general approach to show tooltip, fix temporary tooltip bug (go-gitea#23574)
  Improve workflow event triggers (go-gitea#23613)
  Improve `<SvgIcon>` to make it output `svg` node and optimize performance (go-gitea#23570)
yardenshoham added a commit to yardenshoham/gitea that referenced this pull request Mar 24, 2023
Refactored `deps-docs` out of `docs` because `go-gitea#23629` broke Gitpod's docs setup (which grepped to get the hugo install command).
lunny pushed a commit that referenced this pull request Mar 24, 2023
package doc link is changed in
#23629
GiteaBot pushed a commit to GiteaBot/gitea that referenced this pull request Mar 24, 2023
techknowlogick pushed a commit that referenced this pull request Mar 24, 2023
Refactored `deps-docs` out of `docs` because #23629 broke Gitpod's docs
setup (which grepped to get the hugo install command).

Now `make deps` really installs everything to develop (includes `docs`).
techknowlogick pushed a commit that referenced this pull request Mar 24, 2023
Backport #23679 by @yp05327

package doc link is changed in
#23629

Co-authored-by: yp05327 <576951401@qq.com>
@delvh delvh added this to the 1.20.0 milestone Apr 3, 2023
@go-gitea go-gitea locked and limited conversation to collaborators May 3, 2023
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Labels
backport/done All backports for this PR have been created backport/manual No power to the bots! Create your backport yourself! lgtm/done This PR has enough approvals to get merged. There are no important open reservations anymore. outdated/backport/v1.19 This PR should be backported to Gitea 1.19 type/docs This PR mainly updates/creates documentation
Projects
None yet
Development

Successfully merging this pull request may close these issues.

7 participants