Merge pull request #20 from worldbank/develop

[v1.0, 18SEP2019] develop->master

Author: dianagold

.gitignore

@@ -54,6 +54,7 @@
 !/**/*.sthlp
 !/**/*.toc
 !/**/*.pkg
+!/**/*.txt
 
 # R
 !/**/*.R
@@ -71,12 +72,16 @@
 # Markdown
 !/**/*.md
 
+#######################
+# Ignore folder for experimentation
+personal_test/
+
 #######################
 # Include all the files with passwords or tokens here. All files named
 # password or passwords are with this template ignored no matter which
 # format you are using. Additionally, all content in any folder called
-password or passwords are also ignored. NOTE that your project might be
-using different names and then you must edit the lines below accordingly.
+# password or passwords are also ignored. NOTE that your project might be
+# using different names and then you must edit the lines below accordingly.
 password.*
 passwords.*
 password/

README.md

@@ -1,34 +1,73 @@
-**Edukit - Stata Commands for Education Data Analytics**
+**Edukit - Stata commands for learning assessments**
 =====
-Logo. Blurb about EduAnalytics.
+<img align="left" src="https://user-images.githubusercontent.com/43160181/62169131-58ea6a00-b2f5-11e9-977f-18117cc9e42d.png" width="130">
+
+This toolkit was developed by people that work at or with the **EduAnalytics** team at the World Bank Education Global Practice.
+
+While the commands in this toolkit are developed with best practices for analysis of microdata of learning assessments in mind, some commands may be useful outside that field as well. Some commands are very specific to out own work flow, and might not suit other projects, but we want to share as much as possible for anyone to use if applicable.
+
+
 
 ### **Install and Update**
 
-#### Installing published versions of `edukit`
-One day **edukit** may make it to ssc but for now, it is not, so this option does not exist.
+###### Installing `edukit`
+ **edukit** is currently not published on [SSC](https://www.stata.com/support/ssc-installation/), so it cannot be installed through `ssc install`.
+
+If you want to install the most recent carefully curated version of  **edukit** then you can use the code below:
+
+```
+net install edukit, from("https://raw.githubusercontent.com/worldbank/eduanalyticstoolkit/master/src") replace
+```
+
+The code above installs the version currently in the `master` branch. We merge **edukit** to the `master` branch after we have carefully added new features and documented them in help files.
 
-#### Installing unpublished branches of this repository
-Follow the instructions above if you want the most recent published version of **edukit**.
-If you want a yet to be published version of **edukit** then you can use the code below.
-The code below installs the version currently in the `master` branch, but replace _master_ in the URL below
-with the name of the branch you want to install from. You can also install older version of **edukit**
-like this.
+If you want to install a version of **edukit** not yet merged to the `master` branch then replace _master_ in the URL above with the name of the branch you want to install from. These versions of **edukit** have not yet been equally carefully tested for bugs, and might have features that are not yet documented in the help files, but you are still free to use them.
 
+Similarly, to get the ancillary file in this package (_edukit_save_dyntext.txt_), you can use the code below.
 ```
-    net install edukit , from("https://raw.githubusercontent.com/worldbank/eduanalyticstoolkit/master/src") replace
+net get edukit, from("https://raw.githubusercontent.com/worldbank/eduanalyticstoolkit/master/src") replace
 ```
 
+###### Updating `edukit`
+To update **edukit** simply repeat the installation process that overwrites the files you currently have installed.
+
+#### Installing `edukit` by cloning this repository
+An alternative to those who prefer not to use `net install` in Stata, is to install this package by cloning this repo and checking out the branch you choose to install (_master_ will be checked out by default). To update the package if the branch is updated, you would need to _pull_ the branch. The installation of the package through this method can be automated in your do file through the code below.
+
+```stata
+* Specify the location of the clone of EduAnalytics toolkit repo
+global edukit_clone  "C:/Users/WB111111/Documents/Github/EduAnalyticsToolkit"
+
+* Load eduanalytics toolkit package
+cap net uninstall edukit
+net install edukit.pkg, from("${edukit_clone}/src") replace
+```
+
+This would be the best method to use if you need to adapt these commands to meet the needs specific to your own project.
+
 ### **Content**
 **edukit** provides a set of commands that address different aspects of data management and data analysis for
-International/National Learning Assessments (ILA/NLA) microdata databases.
-The list of commands will be extended continuously, and suggestions for
+learning assessments microdata. The list of commands will be extended continuously, and suggestions for
 new commands are greatly appreciated.
 
  - **edukit** returns meta info on the version of _edukit_ installed.
  Can be used to ensure that the team uses the same version.
+ - **edukit_comparefiles** compares two files and list all the differences.
+It is similar to _cf_, but better at handling different number of observations,
+the data doesn't need to be sorted, and it can create a markdown file of the differences.
+ - **edukit_datalibweb** calls _datalibweb_ repeatedly to prevent breaking a loop if connection is temporarily lost or other issues arise while querying many files. _Datalibweb_ is a currently only available for Stata users within the World Bank, so this command is not intended to be used outside the World Bank.
+ - **edukit_dlwcheck** validates file and folders structures in EduAnalytics' network folder.
+ - **edukit_rmkdir** conveniently creates folders and sub-folders recursively.
  - **edukit_save** is a modified version of the save command to ensure quality of databases.
 Before saving, it compress, check _isid_, and has options to store metadata as _char_
-plus flexibility to execute special commands for eduanalytics.
- - **edukit_pandoc** calls pandoc in a shell to convert between two formats.
- Intended to easily convert HTML created by dyndoc to GitHub-flavored Markdown,
- but made in a flexible way that other input and output files are allowed.
+plus flexibility to execute special commands for EduAnalytics.
+It comes with a companion _dyntext_ example.
+- **edukit_save_dyntext** is a txt to be used with _dyntext_ to automatically generate
+documentation for a dataset, based on metadata stored by _edukit_save_. Given that it
+is an ancillary file in the package, it must be downloaded through _net get_ instead of _net install_.
+
+### **Contact**
+The team can be reached at [eduanalytics@worldbank.org](mailto:eduanalytics@worldbank.org).
+
+### **Authors**
+Kristoffer Bjärkefur, Diana Goldemberg

src/ado_files/edukit.ado

@@ -1,11 +1,11 @@
-*! version 0.2 15JUL2019 EduAnalytics eduanalytics@worldbank.org
+*! version 1.0 18SEP2019 EduAnalytics eduanalytics@worldbank.org
 
 capture program drop edukit
 program edukit, rclass
 
 	* UPDATE THESE LOCALS FOR EACH NEW VERSION PUBLISHED
-	local version "0.2"
-	local versionDate "15JUL2019"
+	local version "1.0"
+	local versionDate "18SEP2019"
 
 	syntax [anything]