You are viewing a plain text version of this content. The canonical link for it is here.
Posted to issues@avro.apache.org by GitBox <gi...@apache.org> on 2022/02/24 08:11:02 UTC
[GitHub] [avro] martin-g commented on a change in pull request #1559: AVRO-2175: Migrate to refactored website
martin-g commented on a change in pull request #1559:
URL: https://github.com/apache/avro/pull/1559#discussion_r813610608
##########
File path: doc/README.md
##########
@@ -0,0 +1,146 @@
+# Apache Avro website
+
+This is a repository of Apache Avro website. The repository of Apache Avro can be found [here](https://github.com/apache/avro).
+
+This website is base on [Hugo](https://gohugo.io) and uses [Docsy](https://www.docsy.dev/) theme.
+
+## Getting started
+
+Clone this repository:
+
+```bash
+git clone --recurse-submodules https://github.com/apache/avro-website.git
Review comment:
This is not correct
##########
File path: doc/README.md
##########
@@ -0,0 +1,146 @@
+# Apache Avro website
+
+This is a repository of Apache Avro website. The repository of Apache Avro can be found [here](https://github.com/apache/avro).
+
+This website is base on [Hugo](https://gohugo.io) and uses [Docsy](https://www.docsy.dev/) theme.
+
+## Getting started
+
+Clone this repository:
+
+```bash
+git clone --recurse-submodules https://github.com/apache/avro-website.git
+```
+
+You can now edit your own versions of the site’s source files.
+
+If you want to do SCSS edits and want to publish these, you need to install `PostCSS`
+
+```bash
+npm install
+```
+
+## Work flow
+
+1. Building and running the site locally requires a recent `extended` version of [Hugo](https://gohugo.io).
+You can find out more about how to install Hugo for your environment in our
+[Getting started](https://www.docsy.dev/docs/getting-started/#prerequisites-and-installation) guide.
+Once you've made your working copy of the site repo, from the repo root folder, run:
+
+
+ ```
+ hugo server --navigateToChanged
+ ```
+
+1. Edit .md and .html files in `content/` folder
+1. Once satisfied with the changes, commit them:
+
+ ```
+ git commit -a
+ ```
+
+1. Generate the HTML filse
+stop `hugo server --navigateToChanged` (with Ctrl+C) and run
+
+ ```
+ hugo --gc --minify
+ ```
+
+ This will generate the HTMLs in `public/` folder and this is actually what is being deployed
+
+1. Add the modified HTML files to Git
+
+ ```
+ git add .
+ git rm offline-search-index.<<OLD-HASH>>.json
+ git commit -a
+ git push
Review comment:
These steps should also be removed.
AFAIU the `content/` folder should be copied to nightlies or SVN publish folder.
##########
File path: doc/content/en/docs/next/Contribution guidelines/_index.md
##########
@@ -0,0 +1,97 @@
+---
+title: "Contribution Guidelines"
+linkTitle: "Contribution Guidelines"
+weight: 10
+---
+
+<!--
+
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ https://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+
+-->
+
+## How to contribute to Apache Avro
+
+You can contribute to Apache Avro in many ways, so join us and make Avro better!
+
+### Ways to Contribute to Apache Avro
+
+A lot of work goes into maintaining a project like Avro and we can use your help!
+
+You can help us in many ways:
+
+* Help out other users at our [user](mailto:user@avro.apache.org) mailing list
+* Answer questions on [Stackoverflow](http://stackoverflow.com/questions/tagged/avro)
+* Report [your bugs](https://issues.apache.org/jira/browse/AVRO)
+* Implement new features or fix bugs
+* Improve this site
+
+If you want to help out with one of our bugs or want to implement a feature, consider using our [Github mirror](https://github.com/apache/avro).
+
+---
+
+### Github Mirror for Easy Contributing
+
+Avro is mirrored on github so you can contribute with ease:
+
+1. Fork Avro
+1. Implement your feature or fix the bug, and
+1. Send a pull request.
+
+The Github/Apache integration will send the pull request to our developer list, and we will look at your pull request as soon as we can.
+
+### Fork Avro to your Account
+
+So you have an account registered at Github and are ready to start hacking at Avro. First you need to fork the code to your own Github account.
+
+You can find the official mirror for the Apache Avro project at the following location in the official Apache Software Foundation organisation at Github:
+
+ Apache Avro Github mirror: https://github.com/apache/avro
+
+On this page you will find a button with the label _“Fork”_. Click it or use the button below.
+
+<button><i class="fas fa-code-branch"></i> [Fork Avro on GitHub](https://github.com/apache/avro/fork)</button>
+
+Now you have your own copy of Avro to hack on. You can edit directly in the Github web interface–good for minor fixes like documentation errors or clone the project to your workstation.
+
+### Clone Avro to your Workstation
+
+You can use the tooling for Github to get a copy on your workstation or use the commandline:
+```shell
+$ git clone git@github.com:<your userid>/Avro.git
Review comment:
s/Avro/avro/
##########
File path: doc/README.md
##########
@@ -0,0 +1,146 @@
+# Apache Avro website
+
+This is a repository of Apache Avro website. The repository of Apache Avro can be found [here](https://github.com/apache/avro).
+
+This website is base on [Hugo](https://gohugo.io) and uses [Docsy](https://www.docsy.dev/) theme.
+
+## Getting started
+
+Clone this repository:
+
+```bash
+git clone --recurse-submodules https://github.com/apache/avro-website.git
+```
+
+You can now edit your own versions of the site’s source files.
+
+If you want to do SCSS edits and want to publish these, you need to install `PostCSS`
+
+```bash
+npm install
+```
+
+## Work flow
+
+1. Building and running the site locally requires a recent `extended` version of [Hugo](https://gohugo.io).
+You can find out more about how to install Hugo for your environment in our
+[Getting started](https://www.docsy.dev/docs/getting-started/#prerequisites-and-installation) guide.
+Once you've made your working copy of the site repo, from the repo root folder, run:
+
+
+ ```
+ hugo server --navigateToChanged
+ ```
+
+1. Edit .md and .html files in `content/` folder
+1. Once satisfied with the changes, commit them:
+
+ ```
+ git commit -a
+ ```
+
+1. Generate the HTML filse
+stop `hugo server --navigateToChanged` (with Ctrl+C) and run
+
+ ```
+ hugo --gc --minify
+ ```
+
+ This will generate the HTMLs in `public/` folder and this is actually what is being deployed
+
+1. Add the modified HTML files to Git
+
+ ```
+ git add .
+ git rm offline-search-index.<<OLD-HASH>>.json
+ git commit -a
+ git push
+ ```
+
+
+This way even when the PR modifies a lot of files we can review only the first commit, the meaningful one, with the modified files in `content/` folder
+
+
+## Running a container locally
+
+You can also run avro-website inside a [Docker](https://docs.docker.com/)
+container, the container runs with a volume bound to the `avro-website`
+folder. This approach doesn't require you to install any dependencies other
+than [Docker Desktop](https://www.docker.com/products/docker-desktop) on
+Windows and Mac, and [Docker Compose](https://docs.docker.com/compose/install/)
+on Linux.
+
+1. Build the docker image
+
+ ```bash
+ docker-compose build
+ ```
+
+1. Run the built image
+
+ ```bash
+ docker-compose up
+ ```
+
+ > NOTE: You can run both commands at once with `docker-compose up --build`.
+
+1. Verify that the service is working.
+
+ Open your web browser and type `http://localhost:1313` in your navigation bar,
+ This opens a local instance of the docsy-example homepage. You can now make
+ changes to the docsy example and those changes will immediately show up in your
+ browser after you save.
+
+### Cleanup
+
+To stop Docker Compose, on your terminal window, press **Ctrl + C**.
+
+To remove the produced images run:
+
+```console
+docker-compose rm
+```
+For more information see the [Docker Compose
+documentation](https://docs.docker.com/compose/gettingstarted/).
+
+### Troubleshooting
+
+As you run the website locally, you may run into the following error:
+
+```
+➜ hugo server
+
+INFO 2021/01/21 21:07:55 Using config file:
+Building sites … INFO 2021/01/21 21:07:55 syncing static files to /
+Built in 288 ms
+Error: Error building site: TOCSS: failed to transform "scss/main.scss" (text/x-scss): resource "scss/scss/main.scss_9fadf33d895a46083cdd64396b57ef68" not found in file cache
+```
+
+This error occurs if you have not installed the extended version of Hugo.
+See our [user guide](https://www.docsy.dev/docs/getting-started/) for instructions on how to install Hugo.
+
+## Edit content
+
+The website content is in `content/en` folder. It contains `.md` (Markdown) and `.html` (HTML) files.
+
+### Layouts
+
+To change the layout of any page edit `layouts/<page>/**.html`. If there is no layout for a given page at that location then copy the one provided by the theme and edit it:
+
+ cp themes/docsy/layouts/<xyz> layouts/<xyz>
+
+### Avro version
+
+When a new version of Apache Avro is released:
+
+1. Change the value of `params.avroversion` in `config.toml`
+2. Add a new entry to the `Releases` pages in the `Blog` section, for example:
+```
+cp content/en/blog/releases/avro-1.10.2-released.md content/en/blog/releases/avro-1.11.0-released.md
+```
+
+### API documentation for C/C++/C# modules
+
+The API documentations for C/C++/C# are built by their respective `build.sh dist` implementations. The final HTML should be copied to the `external` folder, for example:
+
+ cp ../avro/build/avro-doc-1.12.0-SNAPSHOT/api/c/* content/en/docs/external/c/
Review comment:
We can remove this section from README and move the `cp ...` command to a shell script that builds the docs for all SDKs and copies it to nightlies/svn
##########
File path: doc/content/en/docs/next/Java API/_index.md
##########
@@ -0,0 +1,28 @@
+---
+title: "Java API"
+linkTitle: "Java API"
+weight: 4
+---
+
+<!--
+
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ https://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+
+-->
+
+The Javadocs could be found [here](https://avro.apache.org/docs/current/api/java/index.html)
Review comment:
This link might get broken once we deploy the new website.
##########
File path: doc/package.json
##########
@@ -0,0 +1,24 @@
+{
+ "name": "tech-doc-hugo",
+ "version": "0.0.1",
+ "description": "Hugo theme for technical documentation.",
+ "main": "none.js",
+ "scripts": {
+ "test": "echo \"Error: no test specified\" && exit 1"
+ },
+ "repository": {
+ "type": "git",
+ "url": "git+https://github.com/google/docsy-example.git"
Review comment:
do we care about these ? I think we can remove anything that is not Avro related here
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@avro.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org