diff --git a/README.md b/README.md deleted file mode 100644 index 02f3306..0000000 --- a/README.md +++ /dev/null @@ -1,142 +0,0 @@ -Hosts Setup Utility -=================== - - - -Introduction ------------- - -Since the Chinese government is using the blocking the internet access to -several websites and web service providers which includes some world famous -sites like Googel, twitter, Facebook, and Wikipedia etc., we designed this -tiny utility in order to help people to get through the Great Firewall. - -Hosts Setup Utility provides basic tools to manage the hosts file on current -operating systems. Users could use these tool to modify the hosts file in -order to visit specified websites or services blocked by Chinese government. -Functions which help users to backup/restore hosts files are also provided. - -Our home page of is . - -You can also visit the project page on Google Code to get our latest news -. - - -License -------- - -Licensed under the GNU General Public License, version 3. You should -have received a copy of the GNU General Public License along with -this program. If not, see . - - -Usage ------ - -* Windows(x86/x64): run hostsutl.exe from the binary excutables package to get - started. - - - "Run as Administrator" is needed for operations to change the hosts - file on Windows Vista or newer. - -* Mac OS X: run HostsUtl application from the binary excutables package to get - started. - - - Because of the locale problem with py2app, the automatic language - selection may not work correctly on Mac OS with binary excutables. - You can just choose the language on your on choice. - -* Linux/X11(Source code): run command "python hostsutl.py" to get started. - - - All platforms with python and the PyQT4 extension could use this - - method to run the source code. - - A desktop environment with QT and python is needed only for - Linux/X11 users. - - "sudo" is needed for operations to change the hosts file. - -(Note if the programe is not running with privileges to modify the hosts file, -a warning message would be shown and you could only do operations like backup -hosts file and update the local data file.) - - -Requirements ------------- - -* Microsoft Windows 2000 or newer for Windows users. - -* Mac OS X 10.6 or newer for Macintosh users. - -* Linux/X11 desktop with QT for Linux/X11 users. - -* Python 2.6/2.7 with PyQT4 extension for develop. - -* py2exe or py2app would be required while making binary excutables for - specified platforms. - - -Available Modules ------------------ - -* hostsutl.py - contains main parts of Hosts Setup Utility. - -* qthostsui.py - contains UI class for the main dialog of Hosts Setup Utility. - -* qthosts_rc.py - contains images used by the main dialog. - -* retrievedata.py - contains tools to read data from the local hosts data - file. - -* utilities.py - contains basic utilities used by Hosts Setup Utility. - - -Tools for Developers --------------------- - -* _build.py - contains tools to make packages for different platforms. - - Usage: _build.py [type] - Options: - type define the platform to make package for. Optional choices - could be: py2exe, py2app, py2tar, py2source - py2exe - Make binary excutables for Windows. The - py2app - Make binary excutables for Mac OS X. The - operations of this option depends on the py2app - distutils extension. - py2app - Make source code packages for X11 users. - py2source - Make source code packages for developers. - -* _pylupdate4.py : contains tools to update the language files for UI. - -* _pyuic4.py : contains tools update the UI code from UI design. - - -The Rest of the Distribution ----------------------------- - -* lang/ - This directory contains language files for Hosts Setup Utility. - The *.qm files would be included in distribution packages. - -* img/ - This directory contains images and Icons used by Hosts Setup - Utility. - The files in this directory would on be included source code package - for developers. - -* mac_res/ - This directory contains resources to make excutables binaries for - Mac OS X. - The files in this directory would on be included source code package - for developers. - -* theme/ - This directory contains QT stylesheet files of the program. - The stylesheet files (*.qss) are used to create the user interface of - Hosts Setup Utility. - -* hostsutl.pro - Project file for QT. - -* qthosts.qrc - Resource file for main dialog designed by QT. - -* qthostsui.ui - UI project file for the main dialog. - - -Author/Maintainer ------------------ -huhamhire diff --git a/README.rst b/README.rst new file mode 100644 index 0000000..c5eb85f --- /dev/null +++ b/README.rst @@ -0,0 +1,157 @@ +################### +Hosts Setup Utility +################### + +Introduction +============ +Since the governments of some countries are using the blocking the internet +access to several websites and web service providers which includes some world +famous sites like Google, YouTube, twitter, Facebook, and Wikipedia etc., we +designed this tiny utility in order to help people getting through the +Internet blockade. + +`Hosts Setup Utility` provides basic tools to manage the hosts file on current +operating systems. It also provides both support for Graphical Desktop +environment with Graphical User Interface (GUI) and CLI environment with +Text-based User Interface (TUI). + +Users could use these tool to modify the hosts to visit specified websites or +services blocked by ISP/government. Functions which help users to +backup/restore hosts files are also provided. + +`Hosts Setup Utility` is designed by `huhamhire-hosts team`. For further +information, please visit our `website `_. + + +Developer Documentation +======================= +Developers could find our project documentation by visiting +``_. + +This documentation contains descriptions of modules and functions which are +used in the current version of `Hosts Setup Utility`. These documents also +provides some optional methods for developers to help improve this tool. + + +License +======= +Licensed under the GNU General Public License, version 3. You should have +received a copy of the GNU General Public License along with this program. +If not, see ``_. + + +System Requirements +=================== +Here are the system requirements needed for using `Hosts Setup Utility`. + + +Graphical User Interface (GUI) +------------------------------ +System requirements to run `Hosts Setup Utility` on Graphical Desktop are +listed here: + +* Microsoft Windows 2000 or newer for Windows users. + +* Mac OS X 10.6 or newer for Macintosh users. + +* Linux/X11 desktop with Python 2 and PyQt4 for Linux/X11 users. + +* Internet access is required for retrieving the latest hosts data file. + + - On some linux distributions, pre-built packages of PyQt4 can be + found in software repositories. For example, you can install PyQt4 on + a debian distribution simplly using: + + .. code-block:: bash + + apt-get install python-qt4 + + +More requirements are needed for developers: + +* Python 2.6/2.7 with PyQt4 extension for developers. + +* py2exe or py2app would be required while making binary excutables for + specified platforms. + + +Text-based User Interface (TUI) +------------------------------- +Any devices with `Python 2` and `Python Standard Library` INSTALLED could run +`Hosts Setup Utility` in TUI mode from a 80x24 terminal. In addition to this, +TUI mode could also be operated via SSH on remote devices/machines/servers. +All you need is a system with Python 2 installed. + + +Get Started +=========== +Since `Hosts Setup Utility` supports both Graphical Desktop environment with +Graphical User Interface (GUI) and CLI/terminal environment with Text-based +User Interface (TUI), users could the way they would like to launch this tool. + +However, GUI mode is highly recommended because several features like +backup/restore hosts file are still not supported in TUI mode currently. + +* If the program is not running with privileges to modify the hosts + file, a warning message would be shown and you could only do operations + like backup hosts file and update the local data file. Plus, TUI mode + could not get started in this condition. + + +Graphical User Interface (GUI) Mode +----------------------------------- +* Windows(x86/x64): Run hoststool.exe from the binary excutables package to + get started. + + - "Run as Administrator" is needed for operations to change the + hosts file on Windows Vista or newer. + +* Mac OS X: Run HostsUtl application from the binary excutables package to get + started. + + - Because of the locale problem with py2app, the automatic language + selection may not work correctly on Mac OS with binary executable + files. You can just choose the language on your on choice. + +* Linux/X11(Source code): Run command "python hoststool.py" to get started. + + - All platforms with Python and the PyQt4 could use this method to run + with the source code. + - A desktop environment with PyQt4 and python is needed only for + Linux/X11 users to start a GUI Session. + + +Text-based User Interface (TUI) Mode +----------------------------------- +* Windows Excutable(x86/x64): + + #. Start a command line(could be `cmd` or `Power Shell`). + + - "Run as Administrator" is needed for operations to change the + hosts file on Windows Vista or newer. + + #. Change directory to the folder contains binary executable files. of + `Hosts Setup Utility`. + + #. Run ``hoststool_tui.exe`` with an argument ``-t`` from the directory to + get started. + +* Python Source Code: + + `Python Source Code` is very easy to be started through any terminals on any + operating systems. + + #. Change your directory to the source script. + + #. Run ``python hoststool.py -t`` in the terminal. Of course, wirte + privileges to access the hosts file on current system is required. If + not, a warning message box would show up and then terminate current + session. + +If current session is running with `cmd` on a non-english Windows system, +command ``chcp 437`` is required by curses to set the default code page. + + +Author/Maintainer +================= +huhamhire ``_ diff --git a/doc/Makefile b/doc/dev/Makefile similarity index 97% rename from doc/Makefile rename to doc/dev/Makefile index 63c1181..14cc5b9 100644 --- a/doc/Makefile +++ b/doc/dev/Makefile @@ -5,7 +5,8 @@ SPHINXOPTS = SPHINXBUILD = sphinx-build PAPER = -BUILDDIR = build +BUILDDIR = ../../document +SOURCEDIR = ./ # User-friendly check for sphinx-build ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1) @@ -15,9 +16,9 @@ endif # Internal variables. PAPEROPT_a4 = -D latex_paper_size=a4 PAPEROPT_letter = -D latex_paper_size=letter -ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source +ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) $(SOURCEDIR) # the i18n builder cannot share the environment and doctrees with the others -I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source +I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) $(SOURCEDIR) .PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext diff --git a/doc/source/conf.py b/doc/dev/conf.py similarity index 100% rename from doc/source/conf.py rename to doc/dev/conf.py diff --git a/doc/source/gpl.rst b/doc/dev/gpl.rst similarity index 100% rename from doc/source/gpl.rst rename to doc/dev/gpl.rst diff --git a/doc/source/gui.rst b/doc/dev/gui.rst similarity index 100% rename from doc/source/gui.rst rename to doc/dev/gui.rst diff --git a/doc/source/hoststool.rst b/doc/dev/hoststool.rst similarity index 100% rename from doc/source/hoststool.rst rename to doc/dev/hoststool.rst diff --git a/doc/source/index.rst b/doc/dev/index.rst similarity index 89% rename from doc/source/index.rst rename to doc/dev/index.rst index c9af68c..fe31d16 100644 --- a/doc/source/index.rst +++ b/doc/dev/index.rst @@ -9,9 +9,9 @@ Internet blockade. Chapter one of this documentation contains a brief introduction of `Hosts Setup Utility` and basic usage to start this tool. While the others -describing modules and functions that is used in the current version of +describing modules and functions that are used in the current version of `Hosts Setup Utility`. These chapters also describes some optional methods -for developers to improve this tool. +for developers to help improve this tool. This is the documentation for `Hosts Setup Utility` |release|, last updated |today|. diff --git a/doc/source/intro.rst b/doc/dev/intro.rst similarity index 98% rename from doc/source/intro.rst rename to doc/dev/intro.rst index 3013502..92c95b2 100644 --- a/doc/source/intro.rst +++ b/doc/dev/intro.rst @@ -38,7 +38,9 @@ listed here: .. note:: On some linux distributions, pre-built packages of PyQt4 can be found in software repositories. For example, you can install PyQt4 on - a debian distribution simplly using :: + a debian distribution simplly using: + + .. code-block:: bash apt-get install python-qt4 diff --git a/doc/make.bat b/doc/dev/make.bat similarity index 97% rename from doc/make.bat rename to doc/dev/make.bat index 7e79005..b7869b9 100644 --- a/doc/make.bat +++ b/doc/dev/make.bat @@ -5,9 +5,10 @@ REM Command file for Sphinx documentation if "%SPHINXBUILD%" == "" ( set SPHINXBUILD=sphinx-build ) -set BUILDDIR=build -set ALLSPHINXOPTS=-d %BUILDDIR%/doctrees %SPHINXOPTS% source -set I18NSPHINXOPTS=%SPHINXOPTS% source +set BUILDDIR=../../document +set SOURCEDIR=./ +set ALLSPHINXOPTS=-d %BUILDDIR%/doctrees %SPHINXOPTS% %SOURCEDIR% +set I18NSPHINXOPTS=%SPHINXOPTS% %SOURCEDIR% if NOT "%PAPER%" == "" ( set ALLSPHINXOPTS=-D latex_paper_size=%PAPER% %ALLSPHINXOPTS% set I18NSPHINXOPTS=-D latex_paper_size=%PAPER% %I18NSPHINXOPTS% diff --git a/doc/source/tui.rst b/doc/dev/tui.rst similarity index 100% rename from doc/source/tui.rst rename to doc/dev/tui.rst diff --git a/doc/source/util.rst b/doc/dev/util.rst similarity index 100% rename from doc/source/util.rst rename to doc/dev/util.rst