Contributing to documentation and writing tests

[Vikas Pandya]

Hello Mathias & team,

It's been only a few days since I started looking at Spray for one of the projects that I am working on. I have liked what I have seen so far. Great work.

Some missing API documentation and reference test code for better understanding APIs forced to dig deeper into spray codebase to gain more insight into API usage and stuff. I think I can help in this department for making future/fellow Sprayers life easier with more complete API documentation(filling in todos) and writing corresponding reference test code. Eventually having scalatest or specs2 test for every exposed API/feature. Let me know.

Thanks,

[Mathias]

Vikas,

filling in the gaps in the docs on spray.io as well as the scaladocs is one of the focus points of this last leg towards a 1.0/1.1/1.2 final release.
So, if you'd like to contribute anything we'd be more than happy to accept a pull-request!

Cheers,
Mathias

---
mat...@spray.io
http://spray.io

> --
> You received this message because you are subscribed to the Google Groups "spray-user" group.
> To unsubscribe from this group and stop receiving emails from it, send an email to spray-user+...@googlegroups.com.
> For more options, visit https://groups.google.com/groups/opt_out.
>
>

[Michael Hamrah]

Vikas, have you gotten started on documenting any of the directives?  I was going to start with documenting some of the spray-routing directives.  I also wrote up a post from my experience with building a spray-routing app:

http://blog.michaelhamrah.com/2013/06/scala-web-apis-up-and-running-with-spray-and-akka/

Feedback appreciated.  

[Ivan Topolnjak]

I think a per directive example filling that huge list of TODOs would be a big step in easing the entrance to spray for newcomers, specially those who don't have a strong Scala + FP background. Trying to understand a directive that does some kind of extraction without an example makes the reader go through functions that produce other functions, hlists + understanding whatever the directive does. I guess that the spray team could provide a simple template for one directive documentation and let the community start adding more and more.. WDYT?

--
You received this message because you are subscribed to the Google Groups "spray-user" group.
To unsubscribe from this group and stop receiving emails from it, send an email to spray-user+...@googlegroups.com.
For more options, visit https://groups.google.com/groups/opt_out.
 
 

--

Ivan Topolnjak

Telefono: +54 11 5880-6560 | Skype: ivantopo

[Michael Hamrah]

Ivan, I was going to start with Entity directive and work from there (http://spray.io/documentation/1.1-M8/spray-routing/marshalling-directives/entity/#entity), following the same pattern of other pages: pull sample code out of other directories.

--
You received this message because you are subscribed to a topic in the Google Groups "spray-user" group.
To unsubscribe from this topic, visit https://groups.google.com/d/topic/spray-user/x2PJUYkn1Vs/unsubscribe.
To unsubscribe from this group and all its topics, send an email to spray-user+...@googlegroups.com.

[Johannes Rudolph]

Hi Michael,

On Sat, Jun 22, 2013 at 4:21 PM, Michael Hamrah <mha...@gmail.com> wrote:

I also wrote up a post from my experience with building a spray-routing app:

http://blog.michaelhamrah.com/2013/06/scala-web-apis-up-and-running-with-spray-and-akka/

Feedback appreciated.  

great introductory post, thanks for sharing. A few things I wondered about (nothing serious):

(worker ? Create(json))

.mapTo[Ok]

.map(result => result)

.recover { case _ => "error" }

 * `.map(result => result)` should have no effect. Is something missing in that line?
 * using `recover` the error will still be reported to the user with a 200 Ok HTTP message. You may want to think about using `reject` instead of `complete` in this case to report the error with a suitable status code. This will need some restructuring of the code so maybe it is out of scope for the article.

 * your sample code on github depends on dispatch fetching in all of its dependencies even if the sample doesn't make use of it

 * the only route you really implemented was the one using POST which makes it somewhat hard to try it out in the browser

But those are just little nitpicks. Thanks again.

Johannes

[Johannes Rudolph]

On Sat, Jun 22, 2013 at 5:37 PM, Ivan Topolnjak <ivan...@gmail.com> wrote:

I think a per directive example filling that huge list of TODOs would be a big step in easing the entrance to spray for newcomers, specially those who don't have a strong Scala + FP background. Trying to understand a directive that does some kind of extraction without an example makes the reader go through functions that produce other functions, hlists + understanding whatever the directive does. I guess that the spray team could provide a simple template for one directive documentation and let the community start adding more and more.. WDYT?

Absolutely, even if you are no beginner you can figure out things much faster if there are examples to start with.

Thanks a lot for offering to help with the documentation. I agree it makes sense to have a template/example documentation page to start with so that all directives are documented in a similar way. I'll try to come up with something tomorrow.

 

--
Johannes

-----------------------------------------------
Johannes Rudolph
http://virtual-void.net

[Michael Hamrah]

Johannes, thanks for the feedback!  I made the following changes:

- Added a string interpolation message to map(result) to beef it up a little.  

- I added some simple curl commands to test the requests.  I wanted to focus on Spray as an API.  The links are covered in Spray's example; and felt covering it here would be too much.  Curl seems like a balance.

- I removed dispatch; that was just a carryover library from my g8 template.

Finally, I agree the error case should return a 500 error or some other 5xx code.  I'll add that in soon.

Again, thanks for the feedback.  Greatly appreciated.  

[Johannes Rudolph]

Hi,

I posted a PR [1] with a suggested documentation format for directives. You may start your documentation work based on this PR or wait until Mathias has reviewed and merged it to be safe that this will be the accepted structure. I would suggest to start with the simpler directives. Maybe you can drop a note here on which section you are working so that no double work is done.

We decided the examples to be full tests. This way we can document both route code and test code side-by-side.

Maybe you have figured out but working on the documentation basically works like this:

 * Install sphinx: http://sphinx-doc.org/ (`apt-get install python-sphinx` in ubuntu)

 * set the SPHINX_PATH environment variable to point to the sphinx_build script (e.g. `/usr/bin/sphinx-build` in my ubuntu)

 * run sbt

 * `project site`

 * re-start

 * browse to `localhost:8080`

 * `~ products` to automatically rebuild the sphinx site when some source file has changed

 * change documentation

 * reload page

 * go 2 steps back

Examples in the documentation are all executable tests. See the PR on where to put example code. Before committing run `test` in the `docs` project to make sure the tests compile.

Thanks again,

Johannes

[1] https://github.com/spray/spray/pull/341

--

You received this message because you are subscribed to the Google Groups "spray-user" group.

To unsubscribe from this group and stop receiving emails from it, send an email to spray-user+...@googlegroups.com.

For more options, visit https://groups.google.com/groups/opt_out.
 
 

[Ivan Topolnjak]

Nice to see this Johannes, It is a very nice start! I saw the files in the PR and seems pretty obvious how to write them, even while I have never used sphinx before.. let's see what Mathias thinks about it and then I can start pushing some stuff, best regards!

[Mathias]

Ivan,

yes, this is an excellent starting point for the directive docs.
Johannes' PR just got merged into master, so the road is clear for contributions.

Thanks for helping!

Cheers,
Mathias

---
mat...@spray.io
http://spray.io

> *
> *
> *Ivan Topolnjak*
> *Telefono: +54 11 5880-6560 | Skype: ivantopo*

[Birju Patel]

Johannes,

I am trying to setup sphinx on Mac OS X. There isn't a brew install so I manually downloaded and set up SPHINX_PATH into .profile. 

1)sbt "project site" shell runs fine 

2) but while running re-start I keep getting following. permissions into SPHINX dir is chmod 777. seems like something stupid that I am missing.  Any idea?

[trace] Stack trace suppressed: run last site/*:sphinx-compile for the full output.

[error] (site/*:sphinx-compile) java.io.IOException: Cannot run program "/Users/birjupat/birkenfeld-sphinx-e5ad8ce30a8a": error=13, Permission denied

[Ivan Topolnjak]

Birju, I just got this working on my mac and probably the easiest way to get all that is needed is through macports as pointed out in the sphinx site [1], then the SPHINX_PATH env variable should (counterintuitively) point to the sphinx-build script itself, not the path where it is placed which I think is the error you are seeing now.. hope it helps!

[1] http://sphinx-doc.org/latest/install.html#mac-os-x-install-sphinx-using-macports

[Thomas Lockney]

On Friday, June 28, 2013 8:13:53 PM UTC-7, Birju Patel wrote:

Johannes,

I am trying to setup sphinx on Mac OS X. There isn't a brew install so I manually downloaded and set up SPHINX_PATH into .profile.

 

There isn't a brew install because Sphinx is a Python library/module, which brew explicitly doesn't manage (see [1] for more on Python libs and Homebrew). Assuming you've already done `brew install python`, which you might want to do to use a more up-to-date and complete version of Python than what OSX ships, you can run 'pip install sphinx' to get it installed. You can probably get this working with the system installed version of Python, too, but it's going to be more painful. 

~thomas

[1]: https://github.com/mxcl/homebrew/wiki/Homebrew-and-Python

[Johannes Rudolph]

Thanks Thomas for helping out. I'm running on Linux so no advice from me about how to proceed on Mac OS with this. Mathias is running on Mac OS so if you are still having problems getting this running please keep asking (and afterwards we should update developer documentation with the needed steps).

Johannes

--

You received this message because you are subscribed to the Google Groups "spray-user" group.

To unsubscribe from this group and stop receiving emails from it, send an email to spray-user+...@googlegroups.com.

For more options, visit https://groups.google.com/groups/opt_out.
 
 

[Birju Patel]

Thomas thanks. I did do 'pip install sphinx' as you suggested. 

sbt "project site" shell continues working w/o error but now with 're-start' I get following. Any idea what could I be missing?

[error] Error: The Docutils library cannot be found. Did you install Sphinx and its dependencies correctly?

[trace] Stack trace suppressed: run last site/*:sphinx-compile for the full output.

[error] (site/*:sphinx-compile) Error compiling sphinx sources

[Michael Hamrah]

Johannes,

I was trying to make two changes to my sample project and have been having difficulty.  I'd like to:

1) If successful, set the response status code to spray.http.StatusCodes.Created

2) If a failure, log a message and return a spray.http.StatusCodes.InternalServerError

I can do each one of these individually but cannot string it together correctly in a future with the ask pattern.  Any suggestions?

Thanks,

Mike

[Michael Hamrah]

I found this thread which does the job; curious if there's a different approach:

https://groups.google.com/forum/#!searchin/spray-user/InternalServerError/spray-user/ni7k050Ezzg/25rQrzD0WNUJ

[Mathias]

For the record, I replied in the thread you linked to.

Cheers,
Mathias

---
mat...@spray.io
http://spray.io

[Mathias]

Birju,

I installed python (currently version 2.7.5) via homebrew and then sphinx via pip.
With this in my dot file:

export SPHINX_PATH=/usr/local/share/python/sphinx-build

everything works nicely for me.

Can you properly run `sphinx-build` from your command line?
The error you are seeing suggest some borkedness of your python packages.
Or maybe the JVM forked off by revolver somehow runs a different python environment.

When I run `pip list` I see these packages (among others):

- docutils (0.10)
- Sphinx (1.2b1)
- Pygments (1.6)

HTH and cheers,

Mathias

---
mat...@spray.io
http://spray.io

[Birju Patel]

Hi Mathias,

Sorry to be annoying here but this sphinx installation is driving me crazy. I have followed installation just like yours only diff is I see sphinx installed on a following python directory path 

/usr/local/lib/python2.7/site-packages

and in my .profile file I have manually added "export SPHINX_PATH=/usr/local/lib/python2.7/site-packages/sphinx" while running

sbt "project site" shell works w/o any errors but upon 

're-start' it throws 

error] (site/*:sphinx-compile) java.io.IOException: Cannot run program "/usr/local/lib/python2.7/site-packages/sphinx": error=13, Permission denied

I can say this isn't a permissioning issue since all directories and files have chmod 777 privileges. I think my SPHINX installation/SPHNIX_PATH is screwed up/or wrong somehow? I am running OS X 10.8.4. any help is appreciated.

Thanks

[Mathias]

Birju,

the `SPHINX_PATH` env variable needs to point to the `sphinx-build` script.
Try setting it like this:

export SPHINX_PATH=/usr/local/share/python/sphinx-build

Even though sphinx itself is installed in /usr/local/lib/python2.7/site-packages/sphinx the executables live in another directory.
What output do you get for `which sphinx-build`?
This is the path you need to set SPHINX_PATH to.

Cheers,

Mathias

---
mat...@spray.io
http://spray.io

On 10.07.2013, at 23:21, Birju Patel <birj...@gmail.com> wrote:

> Hi Mathias,
>
> Sorry to be annoying here but this sphinx installation is driving me crazy.
> I have followed installation just like yours only diff is I see sphinx
> installed on a following python directory path
> /usr/local/lib/python2.7/site-packages
>
> and in my .profile file I have manually added "export
> SPHINX_PATH=/usr/local/lib/python2.7/site-packages/sphinx" while running
>
> sbt "project site" shell works w/o any errors but upon
> 're-start' it throws

> *error] (site/*:sphinx-compile) java.io.IOException: Cannot run program
> "/usr/local/lib/python2.7/site-packages/sphinx": error=13, Permission denied
> *
> *
> *

> I can say this isn't a permissioning issue since all directories and files
> have chmod 777 privileges. I think my SPHINX installation/SPHNIX_PATH is
> screwed up/or wrong somehow? I am running OS X 10.8.4. any help is
> appreciated.
>
> Thanks

> *
> *

> On Wednesday, July 3, 2013 10:30:47 AM UTC-4, Mathias wrote:
>>
>> Birju,
>>
>> I installed python (currently version 2.7.5) via homebrew and then sphinx
>> via pip.
>> With this in my dot file:
>>
>> export SPHINX_PATH=/usr/local/share/python/sphinx-build
>>
>> everything works nicely for me.
>>
>> Can you properly run `sphinx-build` from your command line?
>> The error you are seeing suggest some borkedness of your python packages.
>> Or maybe the JVM forked off by revolver somehow runs a different python
>> environment.
>>
>> When I run `pip list` I see these packages (among others):
>>
>> - docutils (0.10)
>> - Sphinx (1.2b1)
>> - Pygments (1.6)
>>
>> HTH and cheers,
>> Mathias
>>
>> ---

>> mat...@spray.io <javascript:>
>> http://spray.io
>>
>> On 01.07.2013, at 17:14, Birju Patel <birj...@gmail.com <javascript:>>

>> an email to spray-user+...@googlegroups.com <javascript:>.

[Birju Patel]

Hi Mathias,

I don't see anything when type in which `sphnix-build`. clearly my sphnix installation doesn't look right? 

Though it shows me following upon `pip list`. 

docutils (0.10)

Pygments (1.6)

Sphinx (1.2b1)

Any thoughts?

Thanks,

[Birju Patel]

Hello,

finally I was able to come back to this today and got sphinx setup up & running. http://localhost:8080/ shows me "Say hello to Spray-Can" with some defined Resources like "/ping", "stream", "server-stats" etc. how/where do I see and edit documentation? 

Thanks,

On Monday, June 24, 2013 10:43:22 AM UTC-4, Johannes Rudolph wrote:

[Johannes Rudolph]

Hi Birju,

On Sun, Aug 4, 2013 at 1:20 PM, Birju Patel <birj...@gmail.com> wrote:

Hello,

finally I was able to come back to this today and got sphinx setup up & running. http://localhost:8080/ shows me "Say hello to Spray-Can" with some defined Resources like "/ping", "stream", "server-stats" etc. how/where do I see and edit documentation? 

seems you ran one of the examples instead of the documentation site. Use `project site` and then `re-start` to run the documentation site.

[Age Mooij]

The actual documentation is in the "docs" folder in the form of reStructuredText files. The "site" project takes this as input and turns it into an intermediate form called fjson, which is then served as html by running the "site" project with sbt run.

Age

[Birju Patel]

Hi Johannes,

Sorry to sound lame but i am not sbt expert so may be I am doing something wrong here in starting the project? when I run sbt `project site` i see

-bash: project: command not found

[info] Loading project definition from /Users/birjupat/spray/project

[info] Set current project to root (in build file:/Users/birjupat/spray/)

root > 

re-start shows me following log. not sure why 'site' isn't started. you can  see that log message below. Any idea please?

[info] Recompiling Sphinx sources...

[info] /usr/local/bin/sphinx-build -b json -d /Users/birjupat/spray/site/target/scala-2.10/resource_managed/main/sphinx/doctrees -D version=1.1-SNAPSHOT -D release=1.1-SNAPSHOT /Users/birjupat/spray/docs /Users/birjupat/spray/site/target/scala-2.10/resource_managed/main/sphinx/json

[info] Stopping application echo-server (by killing the forked JVM) ...

[info] Stopping application server-benchmark (by killing the forked JVM) ...

[info] Stopping application simple-http-server (by killing the forked JVM) ...

[info] Running Sphinx v1.1.3

[info] Stopping application simple-routing-app (by killing the forked JVM) ...

[info] Stopping application on-spray-can (by killing the forked JVM) ...

[info] loading pickled environment... done

[info] building [json]: targets for 0 source files that are out of date

[info] updating environment: 0 added, 0 changed, 0 removed

[info] looking for now-outdated files... none found

[info] no targets are out of date.

[info] Starting application echo-server in the background ...

echo-server Starting spray.examples.Main.main()

echo-server ... finished with exit code 143

server-benchmark ... finished with exit code 143

[info] Starting application server-benchmark in the background ...

server-benchmark Starting spray.examples.Main.main()

simple-http-server ... finished with exit code 143

[info] Starting application simple-http-server in the background ...

simple-http-server Starting spray.examples.Main.main()

[info] Starting application simple-routing-app in the background ...

simple-routing-app ... finished with exit code 143

simple-routing-app Starting spray.examples.Main.main()

[info] Starting application on-spray-can in the background ...

on-spray-can ... finished with exit code 143

on-spray-can Starting spray.examples.Boot.main()

server-benchmark     178   1       java.lang.String::hashCode (64 bytes)

server-benchmark     244   2       java.lang.String::charAt (33 bytes)

server-benchmark     246   3       sun.nio.cs.UTF_8$Encoder::encodeArrayLoop (490 bytes)

server-benchmark     269   4       java.util.Properties$LineReader::readLine (452 bytes)

[info] Stopping application site (by killing the forked JVM) ...

server-benchmark     311   5       sun.nio.cs.UTF_8$Decoder::decodeArrayLoop (553 bytes)

server-benchmark     322   6       java.math.BigInteger::mulAdd (81 bytes)

server-benchmark     326   7       java.math.BigInteger::multiplyToLen (219 bytes)

server-benchmark     333   8       java.math.BigInteger::addOne (77 bytes)

server-benchmark     336   9       java.math.BigInteger::squareToLen (172 bytes)

server-benchmark     346  10       java.math.BigInteger::primitiveLeftShift (79 bytes)

server-benchmark     349  11       java.math.BigInteger::montReduce (99 bytes)

server-benchmark     370  12       sun.security.provider.SHA::implCompress (491 bytes)

server-benchmark     408  13       java.lang.Object::<init> (1 bytes)

server-benchmark     461  14       java.io.UnixFileSystem::normalize (75 bytes)

server-benchmark     469  15       java.lang.String::lastIndexOf (156 bytes)

server-benchmark     497  16       java.util.regex.Pattern$Start::match (109 bytes)

server-benchmark     498  17       java.util.regex.Pattern$BmpCharProperty::match (50 bytes)

server-benchmark     500  18       java.util.regex.Pattern$Single::isSatisfiedBy (14 bytes)

server-benchmark     506  19       java.lang.String::indexOf (151 bytes)

server-benchmark     507  20       java.lang.CharacterDataLatin1::getProperties (11 bytes)

server-benchmark     508  21       java.lang.String::equals (88 bytes)

server-benchmark     526  22       java.lang.Math::max (11 bytes)

server-benchmark     526  23       java.util.jar.JarFile::hasClassPathAttribute (168 bytes)

server-benchmark     533  24       java.util.jar.Manifest$FastInputStream::readLine (167 bytes)

server-benchmark     576  25       java.util.regex.Matcher::search (109 bytes)

server-benchmark     588  26       java.lang.String::indexOf (7 bytes)

server-benchmark     589  27       java.net.URI$Parser::charAt (9 bytes)

server-benchmark     591  28       java.net.URI::match (50 bytes)

server-benchmark     591  29       java.lang.AbstractStringBuilder::append (40 bytes)

server-benchmark     592  30       java.lang.StringBuilder::append (8 bytes)

server-benchmark     595  31  !    sun.net.www.ParseUtil::decode (194 bytes)

server-benchmark     602  32       java.math.BigInteger::subN (46 bytes)

server-benchmark     605  33       java.math.MutableBigInteger::mulsub (110 bytes)

server-benchmark ---   n   java.lang.System::arraycopy (static)

server-benchmark     612  34       java.lang.String::indexOf (166 bytes)

server-benchmark     620  35       java.lang.String::startsWith (78 bytes)

site ... finished with exit code 143

[info] Starting application site in the background ...

site Starting spray.site.Main.main()

server-benchmark     644  36       sun.net.www.ParseUtil::encodePath (336 bytes)

server-benchmark     652  37       java.lang.String::lastIndexOf (151 bytes)

server-benchmark     672  38       java.lang.Math::min (11 bytes)

[success] Total time: 2 s, completed Aug 4, 2013 4:58:39 PM

server-benchmark     766  39       java.lang.AbstractStringBuilder::append (60 bytes)

server-benchmark     771  40       java.lang.String::replace (142 bytes)

root > server-benchmark     799  41       java.util.AbstractCollection::isEmpty (13 bytes)

server-benchmark     800  42       java.io.BufferedReader::ensureOpen (18 bytes)

server-benchmark     801  43  !    com.typesafe.config.impl.Tokenizer$TokenIterator::nextCharRaw (70 bytes)

server-benchmark     801  44  !    java.io.BufferedReader::read (104 bytes)

server-benchmark     805  45       java.lang.StringBuilder::appendCodePoint (8 bytes)

server-benchmark     806  46       java.lang.AbstractStringBuilder::appendCodePoint (97 bytes)

server-benchmark     809  47       java.lang.Character::isValidCodePoint (16 bytes)

server-benchmark     809  48       com.typesafe.config.impl.Tokenizer$TokenIterator::pullComment (77 bytes)

server-benchmark     826  49       java.lang.StringBuilder::append (8 bytes)

server-benchmark     827  41      made not entrant  java.util.AbstractCollection::isEmpty (13 bytes)

server-benchmark     855  50       java.util.HashMap::indexFor (6 bytes)

server-benchmark     875  16      made not entrant  java.util.regex.Pattern$Start::match (109 bytes)

server-benchmark     875  17      made not entrant  java.util.regex.Pattern$BmpCharProperty::match (50 bytes)

server-benchmark     875  25      made not entrant  java.util.regex.Matcher::search (109 bytes)

server-benchmark     875  51       java.lang.Character::toLowerCase (162 bytes)

server-benchmark     878  52       java.lang.CharacterDataLatin1::toLowerCase (36 bytes)

server-benchmark     883  53       java.util.HashMap::hash (23 bytes)

server-benchmark     891  43  !   made not entrant  com.typesafe.config.impl.Tokenizer$TokenIterator::nextCharRaw (70 bytes)

server-benchmark     906  54       com.typesafe.config.impl.ConfigImplUtil::isWhitespace (59 bytes)

server-benchmark     914  55       java.nio.Buffer::position (43 bytes)

server-benchmark     916  56       java.util.HashMap::get (79 bytes)

server-benchmark     916  57       java.lang.String::substring (83 bytes)

server-benchmark     926  58       j