Merge pull request #68 from ipfs/reorganize-for-minimal-docs-site

Gather and link existing docs and resources

Author: Mr0grog

.editorconfig

@@ -0,0 +1,11 @@
+[*]
+insert_final_newline = true
+indent_size = 2
+indent_style = space
+trim_trailing_whitespace = true
+
+[*.{md,yaml,yml,toml}]
+indent_size = 4
+
+[Makefile]
+indent_style = tab

.gitignore

@@ -1,5 +1,11 @@
+.vscode
+
 node_modules/
 public/
 tmp/
 themes/material/original/
+
+# Generated source files
 content/reference/pkg/*/
+src/styles/constants.less
+static-build

Makefile

@@ -7,6 +7,7 @@ NPM=npm
 NPMBIN=./node_modules/.bin
 OUTPUTDIR=public
 PKGDIR=content/reference/pkg
+PORT=1313
 
 ifeq ($(DEBUG), true)
 	PREPEND=
@@ -16,23 +17,47 @@ else
 	APPEND=1>/dev/null
 endif
 
+node_modules:
+	$(PREPEND)$(NPM) install $(APPEND)
+
+ipfs-theme:
+	$(PREPEND)[ -d static-build/assets/fonts ] || mkdir -p static-build/assets/fonts
+	$(PREPEND)cp ./node_modules/ipfs-css/fonts/Montserrat* ./static-build/assets/fonts/ $(APPEND)
+	$(PREPEND)cp ./node_modules/ipfs-css/fonts/Inter-UI* ./static-build/assets/fonts/ $(APPEND)
+	$(PREPEND)node scripts/ipfs-css-constants.js $(APPEND)
+
 packages:
-	$(PREPEND)scripts/pkg2md.sh github.com/ipfs/js-ipfs-api master $(PKGDIR) pkg
-	$(PREPEND)scripts/pkg2md.sh github.com/ipfs/js-ipfs master $(PKGDIR) pkg
-	$(PREPEND)scripts/pkg2md.sh github.com/ipfs/go-ipfs-api master $(PKGDIR) pkg
-	$(PREPEND)scripts/pkg2md.sh github.com/ipfs/go-ipfs/core/coreapi master $(PKGDIR) pkg
+	# The JS packages don't actually generate useful docs right now, so skip them
+	# $(PREPEND)scripts/pkg2md.sh github.com/ipfs/js-ipfs-api master $(PKGDIR) pkg
+	# $(PREPEND)scripts/pkg2md.sh github.com/ipfs/js-ipfs master $(PKGDIR) pkg
+	$(PREPEND)scripts/pkg2md.sh github.com/ipfs/go-ipfs-api v1.2.1 $(PKGDIR) go/pkg
+	$(PREPEND)scripts/pkg2md.sh github.com/ipfs/go-ipfs/core/coreapi v0.4.15 $(PKGDIR) go/pkg
+	$(PREPEND)scripts/pkg2md.sh github.com/ipfs/go-ipfs/core/coreapi/interface v0.4.15 $(PKGDIR) go/pkg
+	$(PREPEND)scripts/pkg2md.sh github.com/ipfs/go-ipfs/core/coreapi/interface/options v0.4.15 $(PKGDIR) go/pkg
+
+resources: ipfs-theme packages
+
+install: node_modules resources
 
-build: clean packages
+css:
+	# Dual calls to less because there seems to be a bug with multiple plugins in v3 :(
+	# https://github.com/less/less.js/issues/3187
+	$(PREPEND)$(NPMBIN)/lessc -clean-css --autoprefix src/styles/main.less static-build/assets/main.css $(APPEND)
+
+build: clean install css
 	$(PREPEND)hugo && \
 	echo "" && \
 	echo "Site built out to ./$(OUTPUTDIR)"
 
+dev: css
+	$(PREPEND)( \
+		$(NPMBIN)/nodemon --watch src/styles --ext less,css --exec "$(NPMBIN)/lessc -clean-css --autoprefix src/styles/main.less static-build/assets/main.css" & \
+		hugo server -w --port $(PORT) \
+	)
+
 serve:
 	$(PREPEND)hugo server
 
-node_modules:
-	$(PREPEND)$(NPM) i $(APPEND)
-
 deploy:
 	export hash=`ipfs add -r -Q $(OUTPUTDIR)`; \
 		echo ""; \
@@ -47,5 +72,6 @@ deploy:
 clean:
 	$(PREPEND)[ ! -d $(OUTPUTDIR) ] || rm -rf $(OUTPUTDIR)
 	$(PREPEND)[ ! -d $(PKGDIR) ] || rm -rf $(PKGDIR)/*/
+	$(PREPEND)[ ! -d static-build/assets ] || rm -rf static-build/assets/*
 
 .PHONY: packages build help deploy publish-to-domain clean

README.md

@@ -1,28 +1,39 @@
 # IPFS Docs
 
-> Documentation website for the IPFS project
+This repo is used to:
 
-For now: ipns://beta.docs.ipfs.io and https://beta.docs.ipfs.io
+1. Organize documentation work across the IPFS project
+2. Host a documentation website for IPFS meant to replace what is currently at https://ipfs.io/docs
 
-Read the Captain's Log for updates: [ipfs/docs#47](https://github.com/ipfs/docs/issues/47)
-
-- Overview
-- Contributing content
-- Developing the site
-- Automatic builds
-- FAQ
-  - Why is it critical this is a static site?
-- License
+Read the Captain's Log or check the [issues](https://github.com/ipfs/docs/issues) for updates: [ipfs/docs#47](https://github.com/ipfs/docs/issues/47)
 
 
 ## Overview
 
-TODO
+IPFS documentation currently has several acute problems:
+
+- There is **no clear introduction to the overall idea of exactly how IPFS works and what it’s doing.**
+- IPFS has **lots of new concepts** (whether you are knowledgeable about things like graphs or not) that are just very different from the web technologies people know today.
+- **Docs are inconsistently located** and spread across a number of repos people have to hunt through.
+- Clear, **standard API docs** are not always available.
+- **Hunting through GitHub is hard.** (Which repos have docs? Where in the repo are they? Which projects are important and how do they relate to the others? Which repos and docs are up-to-date?)
+
+We aim to solve some of these problems through a documentation site (the source of which is in this repo) and others through organizing work, conventions, and practices across project repos (managed in the issues here).
 
 
 ## Contributing content
 
-TODO
+The documentation site contains several different kinds of content:
+
+1. **Introductory overviews.** This lives in `content/introduction`. If you spot a problem or have improvements, please post an issue or PR. Please also take a look at [#60](https://github.com/ipfs/docs/issues/60) for planning and ongoing work in this area.
+
+2. **Guides, examples, and tutorials.** Most examples currently live in other repos, like [js-ipfs examples](https://github.com/ipfs/js-ipfs/tree/master/examples). If you have thoughts on how to better integrate them, please file an issue here. If you have feedback on individual examples or want to add a new one, please file an issue or PR on the relevant repo. If you have ideas for guides or tutorials, they belong here! Please propose them in an issue here before creating a PR.
+
+3. **Reference Documentation.** Please see the issues in this repo for current activity around reference/API documentation.
+
+4. **Community.** If there are important missing community links, file an issue or PR here!
+
+Before posting a PR with documentation changes, please also check [out styleguide](https://github.com/ipfs/community/blob/master/docs-styleguide.md).
 
 
 ## Developing the site
@@ -35,28 +46,32 @@ TODO
     ```sh
     npm install -g aegir
     ```
-    
+
 3. Download IPFS libraries and tools (e.g. go-ipfs, js-ipfs) and generate their documentation:
 
     ```sh
-    make packages
+    make install
     ```
-    
-    (Repeat this step anytime a package with autogenerated documentation has a new release.)
+
+    This installs dependencies and generates source files from other projects (e.g. API documentation; theme resources from the `ipfs-css`, etc).
+
+    When dependencies or external packages (like `go-ipfs`) have new releases, regenerate files based on them by running `make resources`.
 
 
 ### Build and Run the Site
 
-* In the root directory, run `make serve`
+* In the root directory, run `make dev`
 * Load http://localhost:1313 in your web browser
 * Edit and add things!
 
+To create a production build, run `make build` instead. You’ll find the final static site in the `public` directory.
+
 
 ## FAQ
 
-### Why is it critical this is a static site?
+### Why is this is a static site?
 
-TODO
+We believe in hosting IPFS’s documentation on IPFS, and that’s much easier when the content is static.
 
 
 ## License