Wiki import

Restart the repository by
1. Starting to use Antora
2. Moving over some packaging related pages over from the wiki
3. Updating the pages where there are obvious problems

README.md

@@ -1,17 +1,131 @@
-# packaging docs 
+# Fedora Packaging Committee
 
-## Running the server for writing new articles
+Welcome!  This is the Pagure instance for the Fedora Package Maintainer Docs.
 
-Running the pelican development server is useful when writing new articles. The steps to
-get it running are:
+The Pagure repository is used to store the source of Package Maintainer Docs,
+track related issues
+and accept changes via pull requests.
 
-1. Install pelican:
-  ````
-  sudo dnf install python2-pelican python2-GitPython
-     python-beautifulsoup4 rubygem-asciidoctor
-  ````
+You can view the actual packaging guidelines
+[here](https://docs.fedoraproject.org/en-US/package-maintainers/).
 
-2. Check out the packagin docs source (from your fork or the main repo)
-3. In the main folder of the checked out repo, run `./develop_server.sh start`
-and your local copy of the Docs Fedora will be at http://localhost:8000/
-4. To stop the development server, run `./develop_server.sh stop`
+## Documentation Development
+
+### Writing
+
+[Antora](https://antora.org/) is used for
+managing the various documents which comprise the guidelines
+and integrating them into the rest of Fedora Documentation.
+
+The guidelines themselves are written in
+[AsciiDoc](https://asciidoc.org).
+Some useful information about AsciiDoc can be found below:
+
+* [AsciiDoc Syntax Quick Reference](https://asciidoctor.org/docs/asciidoc-syntax-quick-reference/)
+* [AsciiDoc Writer's Guide](https://asciidoctor.org/docs/asciidoc-writers-guide/)
+
+### Conventions and Preferences
+
+This repository attempts to follow the following:
+
+* Use [Semantic Line Breaks](http://sembr.org/) to make diffing simpler.
+* Prefer `https://example.com[here]` over `link:https://example.com[here]`
+* Prefer `[#some-ref]` over `[[some-ref]]`
+
+### Local preview
+
+This repo includes scripts to
+build and preview the contents of this repository.
+
+**NOTE**: Please note that
+if you reference pages from other repositories,
+such links will be broken in this local preview
+as it only builds this repository.
+If you want to rebuild the whole Fedora Docs site,
+please see [the Fedora Docs build repository](https://pagure.io/fedora-docs/docs-fp-o/) for instructions.
+
+Both scripts work on Fedora (using Podman) and macOS (using Docker).
+
+To build and preview the site, run:
+
+```
+$ ./build.sh && ./preview.sh
+```
+
+The result will be available at http://localhost:8080
+
+#### Installing Podman on Fedora
+
+Fedora Workstation doesn't come with Podman preinstalled by default
+— so you might need to install it using the following command:
+
+```
+$ sudo dnf install podman
+```
+
+#### Preview as a part of the whole Fedora Docs site
+
+You can also build the whole Fedora Docs site locally
+to see your changes in the whole context.
+This is especially useful for checking if your `xref` links work properly.
+
+To do this,
+you need to clone the main [Fedora Docs build repository](https://pagure.io/fedora-docs/docs-fp-o),
+modify the `site.yml` file to reference a repo with your changes,
+and build it.
+Steps:
+
+Clone the main repository and cd into it:
+
+```
+$ git clone https://pagure.io/fedora-docs/docs-fp-o.git
+$ cd docs-fp-o
+```
+
+Find a reference to the repository you're changing in the `site.yml` file,
+and change it so it points to your change.
+So for example, if I made a modification to the Modularity docs,
+I would find:
+
+```
+...
+   - url: https://pagure.io/fedora-docs/modularity.git
+     branches:
+       - master
+...
+```
+
+And replaced it with a pointer to my fork:
+```
+...
+   - url: https://pagure.io/forks/asamalik/fedora-docs/modularity.git
+     branches:
+       - master
+...
+```
+
+I could also point to a local repository,
+using `HEAD` as a branch
+to preview the what's changed
+without the need of making a commit.
+
+**Note:** I would need to move the repository under the `docs-fp-o` directory,
+because the builder won't see anything above.
+So I would need to create a `repositories` directory in `docs-fp-o`
+and copy my repository into it.
+
+```
+...
+   - url: ./repositories/modularity
+     branches:
+       - HEAD
+...
+```
+
+To build the whole site,
+I would run the following
+in the `docs-fp-o` directory.
+
+```
+$ ./build.sh && ./preview.sh
+```