aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorbnewbold <bnewbold@robocracy.org>2017-07-14 22:34:03 -0700
committerbnewbold <bnewbold@robocracy.org>2017-07-14 22:34:03 -0700
commit0d8fcb008d487b71aeaba7d8c25f254eb00a5052 (patch)
treeb8943c34f918e748859d4b5c6e382a2ddbefb2af
downloaddivergence-0d8fcb008d487b71aeaba7d8c25f254eb00a5052.zip
divergence-0d8fcb008d487b71aeaba7d8c25f254eb00a5052.tar.gz
start with everything but code
-rw-r--r--.gitignore21
-rw-r--r--LICENSE19
-rw-r--r--README.md49
-rw-r--r--TODO.md13
-rw-r--r--alternatives.md21
5 files changed, 123 insertions, 0 deletions
diff --git a/.gitignore b/.gitignore
new file mode 100644
index 0000000..81a4762
--- /dev/null
+++ b/.gitignore
@@ -0,0 +1,21 @@
+*.o
+*.a
+*.pyc
+#*#
+*~
+*.swp
+.*
+*.tmp
+*.old
+*.profile
+*.bkp
+*.bak
+[Tt]humbs.db
+*.DS_Store
+build/
+_build/
+src/build/
+*.log
+
+# Don't ignore this file itself
+!.gitignore
diff --git a/LICENSE b/LICENSE
new file mode 100644
index 0000000..824054e
--- /dev/null
+++ b/LICENSE
@@ -0,0 +1,19 @@
+Copyright (c) 2017 Bryan Newbold
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..7517471
--- /dev/null
+++ b/README.md
@@ -0,0 +1,49 @@
+
+A simple python script for uploading markdown files to Confluence (a
+proprietary wiki system). If you find yourself needing to publish documentation
+to Confluence at work, but wish that instead you could just write markdown and
+keep it versioned in git instead of contending with browser-mangling javascript
+and pull-down menus, then this tool is for you!
+
+This is crude and one-way: there is no mechanism for synchronizing or retaining
+edits made by peers, won't look the way you want it to, there are no unittests,
+it will mangle your wiki space, and confound your sysadmins. Have Fun!
+
+# Installation and Setup
+
+You need **Python 3**, the **requests** python(3) library, and **pandoc**
+installed first:
+
+ # debian/ubuntu
+ sudo apt install python3 python3-requests pandoc
+
+ # homebrew? guessing here
+ sudo brew install python3 py3-requests pandoc
+
+To experiment you can checkout this repo and run commands locally. If you like
+it you can install system-wide with:
+
+ sudo make install
+
+On the Confluence side, it uses the newer REST API (not the old XML-RPC API)
+and generates complete pages in "Confluence storage" syntax, so if you're lucky
+it will Just Work without needing any administrative intervention.
+
+# Usage
+
+ export CONFLUENCE_USER=`whoami`
+ export CONFLUENCE_PASSWORD="password123"
+ export CONFLUENCE_URL="https://evil-corp.jira.com/wiki/"
+ ./divergence -s "PROD25" Acme_Widget_Docs.md
+
+This will create a new page "Acme Widget Docs" under the space with ID
+"PROD25" (or overwrite it if it already exists). When experimenting you
+probably want to use your personal space, which will be something like
+"~bitdiddle". If you blow away something accidentally, it should be possible to
+revert the push in the wiki interface (this has not been verified).
+
+Multiple files can be uploaded at the same time.
+
+If you have in-line images you'll need to upload them manually. Haven't tried
+it yet.
+
diff --git a/TODO.md b/TODO.md
new file mode 100644
index 0000000..90a0fcc
--- /dev/null
+++ b/TODO.md
@@ -0,0 +1,13 @@
+
+- `--help`
+- installation procedure
+- extract space, title, and/or page ID from pandoc yaml header
+
+Nice to have, but unlikely to be implemented:
+
+- optional table of contents
+- more than just markdown (restructured text, html, etc)
+- configurable banner at the top of rendered pages ("this uploaded from...")
+- color output, one line per file
+- detecting and uploading included image files as attachments.
+ `confluence-sync` does this
diff --git a/alternatives.md b/alternatives.md
new file mode 100644
index 0000000..35c30cf
--- /dev/null
+++ b/alternatives.md
@@ -0,0 +1,21 @@
+
+What alternatives are there?
+----------------------------
+
+[https://github.com/laurencer/confluence-sync]()
+
+`confluence-sync-tool` was the closest thing to what I wanted. I even tried
+hacking in the custom pandoc converter, but ran in to problems with `CNAME`
+code blockes getting mangled and gave up trying to debug in Haskell.
+
+[https://bitbucket.org/atlassianlabs/confluence-pandoc-connect]()
+
+This is intended to run server-side. It's where I found the
+`confluence-storage.lua` pandoc writer.
+
+[https://github.com/lanyonm/markdown-to-confluence-uploader]()
+
+Close, but no cigar. Does a meh job converting markdown to wiki markup, then
+uses Confluence's API to convert to storage format via the XML-RPC API. The
+results are poorly formatted.
+