Publish user guide #169
Comments
|
@cbeams Quick question - is it worth keeping the docs on the www. subdomain as this will save us from purchasing two SSL Certificates? I can work around the Wordpress URL stuff pretty easily so if you told me you wanted https://www.bitsquare.io/docs/* then that would be no problem. Can I also suggest, even though it will be basic HTML, we reference the help pages without a .html extension? I can add a .htaccess file to handle the re-writing. This gives us flexibility later if the docs end up being PHP or using some other server side language. As a side note - I'm very happy to provide the hosting for the docs. subdomain too. I have cPanel/PHP/MySQL hosting on a VPS available. Let me know if that's suitable and who needs FTP logins and I'll set them up. |
I haven't looked lately, but I imagine a non-ecommerce wildcard cert for covering all of bitsquare.io wouldn't be much, would it? Docs don't strictly have to be behind SSL at this early stage, but nice to have and sends the right message. In any case, I'd like to keep systems separate and independent wherever possible (although integrated from a L&F and link navigation point of view). There are a number of reasons for this, but I'll skip them to be brief. Happy to go into detail and discuss further though, if you like.
Sure, that's my plan as well. Simple to implement too, given that the docs in their current form are just single pages. The idea is to deploy them in the following form Sound good?
That's great! Assuming Manfred is OK with a Docker-based approach, all we really need is a fresh Linux box/VM, ideally with it's own IP address so as to simplify the DNS arrangement and allow for the Docker container serving the docs to be mapped directly to port 80. Would that that be possible with your setup? |
|
I'll look into the wildcard cert, should work just fine. I agree that having everything behind SSL is for the best. Sends the right message, helps with Google rankings, etc etc The directory system with index.html and just linking to the directory is even better than my suggestion! Make it happen :) @ManfredKarrer could you please point the A Record for docs.bitsquare.io to 179.43.134.87 for me? @cbeams I'll email you (and CC @ManfredKarrer ) FTP details. Let me know if there are any problems. If it's not suitable we can find something else, but I'm confident the VPS I have will be fine for what you've requested. |
|
I've removed the "Steps" section from the description, as we've taken a quicker path (some of which was discussed via email). We now have, courtesy of @btcll, a CentOS VPS for docs running at 179.43.134.87. Chris and manfred have the credentials.
|
|
Manfred, I've just assigned this to you, as you're on point for the DNS step (though I'm working on my tasks in parallel as well) |
|
@btcll, @cbeams: I just added the DNS entry for http://docs.bitsquare.io. |
|
Nice. Resolves for me. Thanks Manfred. On Oct 8, 2014, at 3:06 PM, Manfred Karrer [email protected] wrote:
|
|
@cbeams created ~/public_html/index.php with a PHP header redirect to the Userguide. Hope this helps, but feel free to delete/change if it doesn't. |
|
@btcll: Looks good already, the only tiny wish I have is to change the red color of the headlines to something less alerting (Bitsquare blue or the like)... |
|
@ManfredKarrer I'm not sure what the CSS options are, but if @cbeams can give me some guidance I am happy to do a Bitsquare CSS document up for the docs. It looks like it is all inline CSS at the moment. |
Documentation generated from AsciiDoc sources in the `docs` directory
may now be deployed to docs.bitsquare.io via SSH using
$ ./gradlew publish
Doing so requires supplying the `bitsquareDocsPassword` property to the
Gradle build. This can be done in one of three ways:
1. ./gradlew publish -PbitsquareDocsPassword=...
2. Add a `bitsquareDocsPassword=...` entry in ~/.gradle/gradle.settings
This is the recommended approach when publishing locally.
3. Provide an environment variable in the form
`ORG_GRADLE_PROJECT_bitsquareDocsPassword=...`. This is the approach
used in the Travis CI build (see Notes below).
The Travis CI build now calls `gradle publish` following each successful
build, meaning that documentation is now continuously published and made
available at http://docs.bitsquare.io.
Notes:
- Regarding the Gradle SSH plugin, see:
https://gradle-ssh-plugin.github.io/ and
https://plugins.gradle.org/plugin/org.hidetake.ssh
- Regarding the use of the `plugins { }` closure in build.gradle (a new
feature in Gradle 2.1), see:
http://www.gradle.org/docs/current/release-notes#easier-use-of-community-plugins
- Regarding the use of the `after_success` hook in .travis.yml, see:
http://docs.travis-ci.com/user/deployment/custom/
- Regarding the use of encrypted environment variables in Travis CI, see:
http://docs.travis-ci.com/user/environment-variables/#Secure-Variables.
In particular, see the use of the `travis` gem and `travis encrypt`.
- Regarding setting Gradle project properties via ORG_GRADLE_PROJECT_*
environment variables, see:
http://www.gradle.org/docs/current/userguide/tutorial_this_and_that.html#sec:gradle_properties_and_system_properties
Resolves #169
|
Update on the SSL - it's only going to cover www.bitsquare.io and bitsquare.io. We could have added docs.bitsquare.io for $99/year -or- paid $200+ for a wildcare SSL Certificate. I decided not to (we can always do this later). This means we need to migrate from docs.bitsquare.io to https://www.bitsquare.io/docs/ Is that okay by you @cbeams ? Or do you have a better suggestion? My intention is to do the migration following the HTTPS being setup. I'll need to email you fresh FTP/SSH info. I'm not sure we ever got to the bottom of the SSH issues for you either so let me know on IRC and we can troubleshoot that further. |
Hey Lloyd, I responded to this at #171 (comment). Thanks. |
|
Hey @btcll and @ManfredKarrer—regarding CSS, I've created #179, so we can track that work independently. |
|
I'm closing this, given that we worked out publication of docs a while ago. Getting to a final draft of the doc for 0.1 (#91) still remains to be done (see my comments there). |
Update Oct 11th: This work is done, just waiting for #91 to actually complete so it can be merged into master.
Background
The Asciidoc-based user guide is being developed under #91. This issue deals with publishing the HTML generated during the build process to the web where folks can get convenient access—and so that Bitsquare can refer directly to the docs as an in-app help system.
Proposal
Let's publish to a
docs.bitsquare.iosubdomain as opposed to something likebitsquare.io/docs. This will allow for maximum independence and flexibility between the main website (#84) (which will be WordPress-based at this point), and the generated documentation, which is purely static HTML and requires nothing more than a basic webserver and ssh/sftp-based deployment.URL scheme requirements
Examples
Different types of guides
Different versions
Snapshot versions
Documentation will be published automatically from the Travis CI build, meaning that we can also have docs specific to the latest snapshot:
"Current" version
A
currentalias always points to the latest released version:/cc @btcll
The text was updated successfully, but these errors were encountered: