[
https://issues.apache.org/jira/browse/AVRO-2175?focusedWorklogId=732168&page=com.atlassian.jira.plugin.system.issuetabpanels:worklog-tabpanel#worklog-732168
]
ASF GitHub Bot logged work on AVRO-2175:
----------------------------------------
Author: ASF GitHub Bot
Created on: 24/Feb/22 08:11
Start Date: 24/Feb/22 08:11
Worklog Time Spent: 10m
Work Description: 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:[email protected]) 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 [email protected]:<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: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
Issue Time Tracking
-------------------
Worklog Id: (was: 732168)
Time Spent: 0.5h (was: 20m)
> website refactor
> ----------------
>
> Key: AVRO-2175
> URL: https://issues.apache.org/jira/browse/AVRO-2175
> Project: Apache Avro
> Issue Type: Task
> Components: community
> Reporter: Sean Busbey
> Assignee: Martin Tzvetanov Grigorov
> Priority: Critical
> Labels: pull-request-available
> Fix For: 1.11.1
>
> Time Spent: 0.5h
> Remaining Estimate: 0h
>
> https://lists.apache.org/thread.html/4b804f4e99dc9975c42af59485225808846648b90015f04ab9787246@%3Cdev.avro.apache.org%3E
--
This message was sent by Atlassian Jira
(v8.20.1#820001)
