diff options
Diffstat (limited to 'docs/en')
| -rw-r--r-- | docs/en/Makefile | 2 | ||||
| -rw-r--r-- | docs/en/rst/api/index.rst | 3 | ||||
| -rw-r--r-- | docs/en/rst/conf.py | 11 | ||||
| -rw-r--r-- | docs/en/rst/installing/iis.rst | 3 | ||||
| -rw-r--r-- | docs/en/rst/installing/linux.rst | 3 | ||||
| -rw-r--r-- | docs/en/rst/installing/optional-post-install-config.rst | 42 | ||||
| -rw-r--r-- | docs/en/rst/installing/quick-start.rst | 28 | ||||
| -rw-r--r-- | docs/en/rst/installing/windows.rst | 2 | ||||
| -rw-r--r-- | docs/en/rst/integrating/apis.rst | 13 |
9 files changed, 69 insertions, 38 deletions
diff --git a/docs/en/Makefile b/docs/en/Makefile index fc9af11e0..8c3621f31 100644 --- a/docs/en/Makefile +++ b/docs/en/Makefile @@ -39,7 +39,7 @@ help: @echo " doctest to run all doctests embedded in the documentation (if enabled)" clean: - -rm -rf $(BUILDDIR)/* + find $(BUILDDIR) -maxdepth 1 -type d -not -name rst -not -name images -not -name . -exec rm -rf {} \; html: $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html diff --git a/docs/en/rst/api/index.rst b/docs/en/rst/api/index.rst index 45055eba1..840bcadd1 100644 --- a/docs/en/rst/api/index.rst +++ b/docs/en/rst/api/index.rst @@ -4,7 +4,8 @@ WebService API Reference ======================== This Bugzilla installation has the following WebService APIs available -(as of the last time you compiled the documentation): +(as of the last time you compiled the documentation). Documentation for +the deprecated :ref:`XML-RPC and JSON-RPC APIs <api-list>` is also available. .. toctree:: :glob: diff --git a/docs/en/rst/conf.py b/docs/en/rst/conf.py index 3330ca76d..a758fd248 100644 --- a/docs/en/rst/conf.py +++ b/docs/en/rst/conf.py @@ -383,4 +383,13 @@ pdf_fit_background_mode = 'scale' # Temporary highlighting of TODO items todo_include_todos = False -extlinks = {'bug': ('https://bugzilla.mozilla.org/show_bug.cgi?id=%s', 'bug ')} +# The readthedocs.org website cannot access POD. +on_rtd = os.environ.get('READTHEDOCS', None) == 'True' + +if on_rtd: + base_api_url = 'https://www.bugzilla.org/docs/5.0/en/html/api/' +else: + base_api_url = '../integrating/api/' + +extlinks = {'bug': ('https://bugzilla.mozilla.org/show_bug.cgi?id=%s', 'bug '), + 'api': (base_api_url + '%s', '')} diff --git a/docs/en/rst/installing/iis.rst b/docs/en/rst/installing/iis.rst index 1670db5f5..320b8f73c 100644 --- a/docs/en/rst/installing/iis.rst +++ b/docs/en/rst/installing/iis.rst @@ -4,7 +4,8 @@ Microsoft IIS ############# Bugzilla works with IIS as a normal CGI application. These instructions assume -that you are using Windows 7. Procedures for other versions are probably similar. +that you are using Windows 7 or Windows 10. Procedures for other versions are +probably similar. Begin by starting Internet Information Services (IIS) Manager. :guilabel:`Start` --> :guilabel:`Administrators Tools` --> diff --git a/docs/en/rst/installing/linux.rst b/docs/en/rst/installing/linux.rst index ff4258e6a..22d0bf735 100644 --- a/docs/en/rst/installing/linux.rst +++ b/docs/en/rst/installing/linux.rst @@ -48,8 +48,7 @@ graphviz patchutils gcc 'perl(Apache2::SizeLimit)' 'perl(Authen::Radius)' 'perl(Authen::SASL)' 'perl(Cache::Memcached)' 'perl(CGI)' 'perl(Chart::Lines)' 'perl(Daemon::Generic)' 'perl(Date::Format)' 'perl(DateTime)' 'perl(DateTime::TimeZone)' 'perl(DBI)' 'perl(Digest::SHA)' 'perl(Email::MIME)' -'perl(Email::MIME::Attachment::Stripper)' 'perl(Email::Reply)' -'perl(Email::Sender)' 'perl(Encode)' 'perl(Encode::Detect)' +'perl(Email::Reply)' 'perl(Email::Sender)' 'perl(Encode)' 'perl(Encode::Detect)' 'perl(File::MimeInfo::Magic)' 'perl(File::Slurp)' 'perl(GD)' 'perl(GD::Graph)' 'perl(GD::Text)' 'perl(HTML::FormatText::WithLinks)' 'perl(HTML::Parser)' 'perl(HTML::Scrubber)' 'perl(IO::Scalar)' 'perl(JSON::RPC)' 'perl(JSON::XS)' diff --git a/docs/en/rst/installing/optional-post-install-config.rst b/docs/en/rst/installing/optional-post-install-config.rst index 91d5245d1..accc48888 100644 --- a/docs/en/rst/installing/optional-post-install-config.rst +++ b/docs/en/rst/installing/optional-post-install-config.rst @@ -115,7 +115,7 @@ Dependency Graphs ================= Bugzilla can draw graphs of the dependencies (depends on/blocks relationships) -between bugs, if you install a package called :file:`dot`. +between bugs, if you install a package called :file:`graphviz`. Linux ----- @@ -129,8 +129,7 @@ Windows Download and install Graphviz from `the Graphviz website <http://www.graphviz.org/Download_windows.php>`_. Put the complete path to :file:`dot.exe` in the :param:`webdotbase` parameter, -using forward slashes as path separators. E.g. -:paramval:`C:/Program Files/ATT/Graphviz/bin/dot.exe`. +e.g. :paramval:`C:\\Program Files (x86)\\Graphviz2.38\\bin\\dot.exe`. Documentation ============= @@ -139,16 +138,37 @@ Bugzilla has extensive documentation and help, written in `reStructured Text <http://sphinx-doc.org/rest.html>`_ format. A generic compiled copy exists on `bugzilla.readthedocs.org <https://bugzilla.readthedocs.org/>`_, and -:guilabel:`Help` links point to it by default. If you want to build and use a -local copy of the documentation, perhaps because you have added Bugzilla +:guilabel:`Help` links point to it by default. You can also build and use +a local copy of the documentation, for instance because you have added Bugzilla extensions which come with documentation, or because your users don't have -Internet access from their machines, then: - -* Install `Sphinx <http://sphinx-doc.org/>`_ - (:file:`python-sphinx` package on Debian/Ubuntu) - -Then run :command:`docs/makedocs.pl` in your Bugzilla directory. +Internet access from their machines. Bugzilla will automatically detect that you've compiled the documentation and link to it in preference to the copy on the Internet. Don't forget to recompile it when you upgrade Bugzilla or install new extensions. + +Linux +----- + +* Install `Sphinx <http://sphinx-doc.org/>`_. Most Linux distros have it in + a package named :file:`python-sphinx`. + +* Then go to your Bugzilla directory and run: + + :command:`docs/makedocs.pl` + +Windows +------- + +* Download and install `Python <https://www.python.org/downloads/>`_. + Both Python 2.7 and 3.x will work. Adding :file:`python` to the :param:`PATH` + environment variable, as suggested by the Python installer, will make your + life easier. + +* Install `Sphinx <http://sphinx-doc.org/>`_. Run :command:`cmd.exe` and type: + + :command:`pip install sphinx` + +* Then go to your :file:`C:\\bugzilla\\docs` directory and run: + + :command:`makedocs.pl` diff --git a/docs/en/rst/installing/quick-start.rst b/docs/en/rst/installing/quick-start.rst index c2da8da23..64a88e55b 100644 --- a/docs/en/rst/installing/quick-start.rst +++ b/docs/en/rst/installing/quick-start.rst @@ -5,8 +5,8 @@ Quick Start (Ubuntu Linux 14.04) This quick start guide makes installing Bugzilla as simple as possible for those who are able to choose their environment. It creates a system using -Ubuntu Linux 14.04 LTS, Apache and MySQL, and installs Bugzilla as the default -home page. It requires a little familiarity with Linux and the command line. +Ubuntu Linux 14.04 LTS, Apache and MySQL. It requires a little familiarity +with Linux and the command line. Obtain Your Hardware ==================== @@ -62,17 +62,13 @@ Download Bugzilla Get it from our Git repository: -:command:`cd /var/www` - -:command:`rm -rf html` +:command:`cd /var/www/html` -:command:`git clone --branch release-X.X-stable https://git.mozilla.org/bugzilla/bugzilla html` +:command:`git clone --branch release-X.X-stable https://git.mozilla.org/bugzilla/bugzilla bugzilla` (where "X.X" is the 2-digit version number of the stable release of Bugzilla -that you want - e.g. 4.4) +that you want - e.g. 5.0) -:command:`cd html` - Configure MySQL =============== @@ -113,7 +109,7 @@ Paste in the following and save: ServerName localhost - <Directory /var/www/html> + <Directory /var/www/html/bugzilla> AddHandler cgi-script .cgi Options +ExecCGI DirectoryIndex index.cgi index.html @@ -135,7 +131,7 @@ generates a config file (called :file:`localconfig`) for the database access information, and the second time (step 10) it uses the info you put in the config file to set up the database. -:command:`cd /var/www/html` +:command:`cd /var/www/html/bugzilla` :command:`./checksetup.pl` @@ -164,7 +160,7 @@ Write down the email address and password you set. Test Server =========== -:command:`./testserver.pl http://localhost/` +:command:`./testserver.pl http://localhost/bugzilla` All the tests should pass. You will get warnings about deprecation from the ``Chart::Base`` Perl module; just ignore those. @@ -178,7 +174,7 @@ Access Via Web Browser Access the front page: -:command:`lynx http://localhost/` +:command:`lynx http://localhost/bugzilla` It's not really possible to use Bugzilla for real through Lynx, but you can view the front page to validate visually that it's up and running. @@ -186,8 +182,8 @@ can view the front page to validate visually that it's up and running. You might well need to configure your DNS such that the server has, and is reachable by, a name rather than IP address. Doing so is out of scope of this document. In the mean time, it is available on your local network -at ``http://<ip address>/``, where ``<ip address>`` is (unless you have -a complex network setup) the "inet addr" value displayed when you run +at ``http://<ip address>/bugzilla``, where ``<ip address>`` is (unless you +have a complex network setup) the "inet addr" value displayed when you run :command:`ifconfig eth0`. Configure Bugzilla @@ -201,7 +197,7 @@ Click the :guilabel:`Parameters` link on the page it gives you, and set the following parameters in the :guilabel:`Required Settings` section: * :param:`urlbase`: - :paramval:`http://<servername>/` or :paramval:`http://<ip address>/` + :paramval:`http://<servername>/bugzilla/` or :paramval:`http://<ip address>/bugzilla/` Click :guilabel:`Save Changes` at the bottom of the page. diff --git a/docs/en/rst/installing/windows.rst b/docs/en/rst/installing/windows.rst index ef1a1f6f4..adc1728c6 100644 --- a/docs/en/rst/installing/windows.rst +++ b/docs/en/rst/installing/windows.rst @@ -89,6 +89,7 @@ Install the following mandatory modules with: * JSON-XS * Win32 * Win32-API +* DateTime-TimeZone-Local-Win32 The following modules enable various optional Bugzilla features; try and install them, but don't worry too much to begin with if you can't get them @@ -125,7 +126,6 @@ installed: * IO-stringy * Cache-Memcached * File-Copy-Recursive -* GraphViz If you are using Strawberry Perl, you should use the :file:`install-module.pl` script to install modules, which is the same script used for Linux. Some of diff --git a/docs/en/rst/integrating/apis.rst b/docs/en/rst/integrating/apis.rst index 6067c12df..54ee3273a 100644 --- a/docs/en/rst/integrating/apis.rst +++ b/docs/en/rst/integrating/apis.rst @@ -12,6 +12,13 @@ coming soon. The APIs currently available are as follows: +Core Module API +=============== + +Most of the core Bugzilla modules have extensive documentation inside the modules +themselves. You can view the :api:`POD documentation <index.html>` to help with +using the core modules in your extensions. + Ad-Hoc APIs =========== @@ -23,8 +30,7 @@ to alternate data formats where they are available. XML-RPC ======= -Bugzilla has an `XML-RPC API -<http://www.bugzilla.org/docs/tip/en/html/api/Bugzilla/WebService/Server/XMLRPC.html>`_. +Bugzilla has an :api:`XML-RPC API <Bugzilla/WebService/Server/XMLRPC.html>`. This will receive no further updates and will be removed in a future version of Bugzilla. @@ -33,8 +39,7 @@ Endpoint: :file:`/xmlrpc.cgi` JSON-RPC ======== -Bugzilla has a `JSON-RPC API -<http://www.bugzilla.org/docs/tip/en/html/api/Bugzilla/WebService/Server/JSONRPC.html>`_. +Bugzilla has a :api:`JSON-RPC API <Bugzilla/WebService/Server/JSONRPC.html>`. This will receive no further updates and will be removed in a future version of Bugzilla. |