enalean / tuleap-documentation-en Goto Github PK

View Code? Open in Web Editor NEW

10.0 20.0 40.0 46.82 MB

Tuleap documentation in reStructuredText format, built with Sphinx

Home Page: https://docs.tuleap.org/

License: Other

Makefile 3.31% Python 15.07% HTML 20.29% JavaScript 8.20% Dockerfile 0.91% SCSS 47.86% Nix 3.17% TypeScript 1.19%

documentation tuleap

tuleap-documentation-en's Introduction

Tuleap Documentation

Tuleap uses Sphinx in order to generate its documentation.

Contributors are encouraged to have a look at Google Technical Writing course in order to add high quality content.

Contribute without leaving your browser

GitPod allows editing and building the documentation without leaving your browser. Give it a try with click on .

Download the sources from GitHub

git clone [email protected]:Enalean/tuleap-documentation-en.git
cd tuleap-documentation-en/

Build the documentation

nix-shell
make html

The documentation is generated in tuleap-documentation-en/_build/html/en/ You can check the modifications by opening index.html with your web browser. You need to build the documentation in order to see your modifications.

To build documentation for tuleap.org:

nix-shell
npm ci
npm run build
make SPHINXOPTS="-D html_theme=tuleap_org" html

To build the documentation in watch mode:

nix-shell
npm ci
npm run build
make SPHINXOPTS="-D html_theme=tuleap_org" watch-html

A web-server will start, the modifies pages will be rebuilt and reloaded automatically each time you save your work.

Modify/ add to the documentation

cd tuleap-documentation-en/languages/en/

There will be a few main folders in here which correspond to documentation sections. To add a new page, create the file in the correct directory then add the reference in index.rst.

Note: All changes must be pushed on the master branch.

License

Tuleap and its documentation are licensed under GPLv2 or above.

tuleap-documentation-en's People

Contributors

Stargazers

Watchers

tuleap-documentation-en's Issues

Punctuation is broken in the intro section of the installation guide

The dot should be after the link not in the middle of the phrase.

tuleap-documentation-en/languages/en/installation-guide/intro.rst

Line 4 in 66dc334

 If you are a tech enthusiast with the ability to self-install and maintain your instance, Tuleap Community Edition (TCE) is available and offer powerful capabilities for non-critical business process or development needs. If you need enterprise-class features, scalability and security and if you plan to use Tuleap in a production environment, you should consider . 

#229

Opening the issue as reminder for myself to fix it.

Lot of broken links

If we run make linkcheck we get a lot of broken links. Here is the full output:

administration-guide/bot-mattermost-plugins.rst:20: [local] ../user-guide/git.html
administration-guide/bot-mattermost-plugins.rst:33: [broken] https://docs.mattermost.com/developer/webhooks-incoming.html#creating-integrations-using-incoming-webhooks: Anchor 'creating-integrations-using-incoming-webhooks' not found
administration-guide/distributed-tuleap.rst:137: [redirected with Found] https://access.redhat.com/documentation/en-US/Red_Hat_Software_Collections/2/html-single/2.3_Release_Notes/index.html#sect-Installation-Subscribe to https://access.redhat.com/documentation/en-us/red_hat_software_collections/2/html-single/2.3_release_notes/index#sect-Installation-Subscribe
administration-guide/files-permissions.rst:40: [broken] http://: Invalid URL u'http://': No host supplied
administration-guide/files-permissions.rst:40: [broken] http://example.com/projects/: 404 Client Error: Not Found for url: http://example.com/projects/
administration-guide/howto.rst:219: [broken] http://lists.example.com/mailman/admin: HTTPConnectionPool(host='lists.example.com', port=80): Max retries exceeded with url: /mailman/admin (Caused by NewConnectionError('<urllib3.connection.HTTPConnection object at 0x7fa4465a5a50>: Failed to establish a new connection: [Errno -2] Name or service not known',))
administration-guide/howto.rst:529: [redirected with Found] http://www.coelho.net/svn-merge-repos.html to https://www.cri.ensmp.fr/people/coelho/svn-merge-repos.html
administration-guide/howto.rst:1034: [redirected permanently] https://medium.freecodecamp.org/how-i-hacked-hundreds-of-companies-through-their-helpdesk-b7680ddc2d4c to https://medium.com/intigriti/how-i-hacked-hundreds-of-companies-through-their-helpdesk-b7680ddc2d4c
administration-guide/run-php56.rst:201: [broken] https://tuleap.example.com/www/projectname/: HTTPSConnectionPool(host='tuleap.example.com', port=443): Max retries exceeded with url: /www/projectname/ (Caused by NewConnectionError('<urllib3.connection.VerifiedHTTPSConnection object at 0x7fa445707bd0>: Failed to establish a new connection: [Errno -2] Name or service not known',))
administration-guide/services.rst:298: [broken] http://projectname.your.example.com: HTTPConnectionPool(host='projectname.your.example.com', port=80): Max retries exceeded with url: / (Caused by NewConnectionError('<urllib3.connection.HTTPConnection object at 0x7fa44572fdd0>: Failed to establish a new connection: [Errno -2] Name or service not known',))
administration-guide/services.rst:473: [redirected with Found] http://www.igniterealtime.org/community/docs/DOC-1080 to https://discourse.igniterealtime.org/t/helga-a-server-bot-plugin/77500/1
deployment-guide/intro.rst:1382: [redirected with Found] https://www.softwarecollections.org to https://www.softwarecollections.org/en/
deployment-guide/intro.rst:1365: [broken] http://www.elasticsearch.org/guide/en/elasticsearch/reference/current/setup-repositories.html#_yum: Anchor '_yum' not found
developer-guide/coding-standards.rst:35: [broken] https://github.com/squizlabs/PHP_CodeSniffer/wiki/Advanced-Usage#ignoring-files-and-folders: Anchor 'ignoring-files-and-folders' not found
developer-guide/coding-standards.rst:9: [redirected permanently] http://www.php-fig.org/psr/psr-0/ to https://www.php-fig.org/psr/psr-0/
developer-guide/coding-standards.rst:10: [redirected permanently] http://www.php-fig.org/psr/psr-1/ to https://www.php-fig.org/psr/psr-1/
developer-guide/coding-standards.rst:11: [redirected permanently] http://www.php-fig.org/psr/psr-2/ to https://www.php-fig.org/psr/psr-2/
developer-guide/gerrit.rst:24: [broken] http://tuleap-gerrit.gerrit-tuleap.docker:8080: HTTPConnectionPool(host='tuleap-gerrit.gerrit-tuleap.docker', port=8080): Max retries exceeded with url: / (Caused by NewConnectionError('<urllib3.connection.HTTPConnection object at 0x7fa4464d3d50>: Failed to establish a new connection: [Errno -2] Name or service not known',))
developer-guide/ldap.rst:40: [redirected permanently] http://stackoverflow.com/questions/20673186/getting-error-for-setting-password-feild-when-creating-generic-user-account-phpl to https://stackoverflow.com/questions/20673186/getting-error-for-setting-password-field-when-creating-generic-user-account-phpl
developer-guide/ldap.rst:36: [redirected permanently] https://github.com/Enalean/docker-ldap-dev to https://github.com/Enalean/docker-ldap
developer-guide/patches.rst:48: [broken] https://gerrit.tuleap.net/#/admin/projects/tuleap: Anchor '/admin/projects/tuleap' not found
developer-guide/patches.rst:98: [broken] https://gerrit.tuleap.net/#/projects/tuleap,dashboards/main:wip: Anchor '/projects/tuleap,dashboards/main:wip' not found
developer-guide/plugins.rst:117: [broken] https://tuleap.example.com/plugins/mercurial: HTTPSConnectionPool(host='tuleap.example.com', port=443): Max retries exceeded with url: /plugins/mercurial (Caused by NewConnectionError('<urllib3.connection.VerifiedHTTPSConnection object at 0x7fa44572fb50>: Failed to establish a new connection: [Errno -2] Name or service not known',))
developer-guide/quick-start/clone-tuleap.rst:24: [broken] https://gerrit.tuleap.net/#/admin/projects/tuleap: Anchor '/admin/projects/tuleap' not found
developer-guide/quick-start/install-docker.rst:60: [redirected permanently] https://www.docker.com/docker-toolbox to https://docs.docker.com/toolbox/
developer-guide/quick-start/run-tuleap.rst:14: [broken] https://github.com/squizlabs/PHP_CodeSniffer#installation: Anchor 'installation' not found
developer-guide/quick-start/run-tuleap.rst:75: [redirected permanently] https://registry.hub.docker.com/u/enalean/tuleap-aio-dev/ to https://hub.docker.com/r/enalean/tuleap-aio-dev/
developer-guide/quick-start/run-tuleap.rst:43: [broken] https://tuleap-web.tuleap-aio-dev.docker: HTTPSConnectionPool(host='tuleap-web.tuleap-aio-dev.docker', port=443): Max retries exceeded with url: / (Caused by NewConnectionError('<urllib3.connection.VerifiedHTTPSConnection object at 0x7fa44611fbd0>: Failed to establish a new connection: [Errno 113] No route to host',))
developer-guide/quick-start/run-tuleap.rst:101: [broken] https://tuleap-web.tuleap-aio-dev.docker/: HTTPSConnectionPool(host='tuleap-web.tuleap-aio-dev.docker', port=443): Max retries exceeded with url: / (Caused by NewConnectionError('<urllib3.connection.VerifiedHTTPSConnection object at 0x7fa446464250>: Failed to establish a new connection: [Errno 113] No route to host',))
developer-guide/release.rst:34: [broken] https://gerrit.tuleap.net/#/admin/projects/tuleap: Anchor '/admin/projects/tuleap' not found
developer-guide/release.rst:104: [redirected permanently] http://semver.org/ to https://semver.org/
developer-guide/trackers.rst:5: [local] ../_images/tracker-structure.png
installation-guide/advanced-configuration.rst:34: [broken] https://yourforge.com/asuffix/: HTTPSConnectionPool(host='yourforge.com', port=443): Max retries exceeded with url: /asuffix/ (Caused by NewConnectionError('<urllib3.connection.VerifiedHTTPSConnection object at 0x7fa445357750>: Failed to establish a new connection: [Errno 111] Connection refused',))
installation-guide/ansible-installation.rst:18: [redirected permanently] https://www.ansible.com/get-started to https://www.ansible.com/resources/get-started
installation-guide/full-installation.rst:118: [broken] http://tuleap.example.com: HTTPConnectionPool(host='tuleap.example.com', port=80): Max retries exceeded with url: / (Caused by NewConnectionError('<urllib3.connection.HTTPConnection object at 0x7fa4467a2f90>: Failed to establish a new connection: [Errno -2] Name or service not known',))
soap/trackerv3.rst:11: [broken] https://tuleap.net/soap/wsdl#op.id1167451753957: Anchor 'op.id1167451753957' not found
user-guide/ci.rst:95: [broken] http://localhost:8080/hudson: HTTPConnectionPool(host='localhost', port=8080): Max retries exceeded with url: /hudson (Caused by NewConnectionError('<urllib3.connection.HTTPConnection object at 0x7fa4461f7790>: Failed to establish a new connection: [Errno 111] Connection refused',))
user-guide/ci.rst:406: [broken] http://[my_ci_server]:8080/hudson/job/[my_job: HTTPConnectionPool(host='my_ci_server', port=8080): Max retries exceeded with url: /hudson/job/[my_job (Caused by NewConnectionError('<urllib3.connection.HTTPConnection object at 0x7fa44c3b1410>: Failed to establish a new connection: [Errno -2] Name or service not known',))
user-guide/ci.rst:95: [broken] https://hudson.dev.java.net/: HTTPSConnectionPool(host='hudson.dev.java.net', port=443): Max retries exceeded with url: / (Caused by NewConnectionError('<urllib3.connection.VerifiedHTTPSConnection object at 0x7fa4461f7590>: Failed to establish a new connection: [Errno -2] Name or service not known',))
user-guide/ci.rst:205: [broken] http://hudson.gotdns.com/wiki/display/HUDSON/Plugins: HTTPConnectionPool(host='hudson.gotdns.com', port=80): Max retries exceeded with url: /wiki/display/HUDSON/Plugins (Caused by NewConnectionError('<urllib3.connection.HTTPConnection object at 0x7fa4461f74d0>: Failed to establish a new connection: [Errno 113] No route to host',))
user-guide/citizen.rst:95: [broken] http://tuleap.example.com/: HTTPConnectionPool(host='tuleap.example.com', port=80): Max retries exceeded with url: / (Caused by NewConnectionError('<urllib3.connection.HTTPConnection object at 0x7fa4461fab90>: Failed to establish a new connection: [Errno -2] Name or service not known',))
user-guide/communication.rst:405: [broken] http://: Invalid URL u'http://': No host supplied
user-guide/communication.rst:408: [redirected permanently] http://tuleap.net to https://tuleap.net/
user-guide/communication.rst:226: [broken] http://www.jabber.org/clients: 404 Client Error: Not Found for url: https://www.jabber.org/clients
user-guide/gerrit.rst:94: [broken] http://gerrit-documentation.googlecode.com/svn/Documentation/2.5.2/access-control.html: 404 Client Error: Not Found for url: http://gerrit-documentation.googlecode.com/svn/Documentation/2.5.2/access-control.html
user-guide/gerrit.rst:8: [redirected with Found] http://code.google.com/p/gerrit/ to https://bugs.chromium.org/p/gerrit/issues/list
user-guide/gerrit.rst:462: [redirected with Found] https://groups.google.com/d/topic/repo-discuss/yJDNZJmmAUI/discussion to https://groups.google.com/forum/#!topic/repo-discuss/yJDNZJmmAUI/discussion
user-guide/git.rst:237: [redirected permanently] http://git-scm.com/ to https://git-scm.com/
user-guide/git.rst:239: [broken] http://progit.org/book/ch1-1.html: HTTPSConnectionPool(host='progit.org', port=443): Max retries exceeded with url: /book/ch1-1.html (Caused by SSLError(SSLError(1, u'[SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed (_ssl.c:590)'),))
user-guide/git.rst:223: [redirected permanently] https://wiki.jenkins-ci.org/display/JENKINS/Git+Plugin#GitPlugin-Pushnotificationfromrepository to https://wiki.jenkins.io/display/JENKINS/Git+Plugin#GitPlugin-Pushnotificationfromrepository
user-guide/intro.rst:28: [redirected permanently] http://www.tuleap.org/ to https://www.tuleap.org/
user-guide/mediawiki.rst:64: [redirected permanently] http://www.mediawiki.org/wiki/Manual:User_rights to https://www.mediawiki.org/wiki/Manual:User_rights
user-guide/mediawiki.rst:101: [redirected permanently] http://www.mediawiki.org/wiki/Extension:PdfBook to https://www.mediawiki.org/wiki/Extension:PdfBook
user-guide/mediawiki.rst:132: [redirected permanently] http://www.mediawiki.org/wiki/Documentation to https://www.mediawiki.org/wiki/Documentation
user-guide/mediawiki.rst:107: [redirected permanently] http://www.mediawiki.org/wiki/Extension:WikiEditor to https://www.mediawiki.org/wiki/Extension:WikiEditor
user-guide/mediawiki.rst:143: [redirected permanently] http://www.organicdesign.co.nz/nad to https://organicdesign.nz/Nad
user-guide/other-services.rst:86: [redirected permanently] http://tuleap.net/soap/ to https://tuleap.net/soap/
user-guide/other-services.rst:91: [redirected with Found] http://tuleap.net/soap/?wsdl to https://tuleap.net/soap/codendi.wsdl.php?wsdl
user-guide/other-services.rst:110: [broken] http://tuleap.net/documentation/cli/html/en_US/: 404 Client Error: Not Found for url: https://tuleap.net/documentation/cli/html/en_US/
user-guide/rest/quick-start/update.rst:59: [broken] https://tuleap.example.com/api/explorer/: HTTPSConnectionPool(host='tuleap.example.com', port=443): Max retries exceeded with url: /api/explorer/ (Caused by NewConnectionError('<urllib3.connection.VerifiedHTTPSConnection object at 0x7fa445529810>: Failed to establish a new connection: [Errno -2] Name or service not known',))
user-guide/testmanagement.rst:178: [broken] https://my.tuleap.tld: HTTPSConnectionPool(host='my.tuleap.tld', port=443): Max retries exceeded with url: / (Caused by NewConnectionError('<urllib3.connection.VerifiedHTTPSConnection object at 0x7fa4467a2190>: Failed to establish a new connection: [Errno -2] Name or service not known',))
user-guide/tracker.rst:1159: [redirected permanently] http://en.wikipedia.org/wiki/Scrum_(development) to https://en.wikipedia.org/wiki/Scrum_(development)
user-guide/tracker.rst:214: [redirected permanently] http://dev.mysql.com/doc/refman/5.0/en/regexp.html to https://dev.mysql.com/doc/refman/5.7/en/regexp.html
user-guide/tracker.rst:245: [redirected permanently] http://dev.mysql.com/doc/refman/5.0/en/regexp.html to https://dev.mysql.com/doc/refman/5.7/en/regexp.html
user-guide/tracker.rst:164: [redirected permanently] http://dev.mysql.com/doc/refman/5.0/en/regexp.html to https://dev.mysql.com/doc/refman/5.7/en/regexp.html
user-guide/tracker-v3.rst:176: [redirected permanently] http://dev.mysql.com/doc/refman/5.0/en/regexp.html to https://dev.mysql.com/doc/refman/5.7/en/regexp.html
user-guide/tracker-v3.rst:1158: [redirected permanently] http://en.wikipedia.org/wiki/Scrum_(development) to https://en.wikipedia.org/wiki/Scrum_(development)
user-guide/tracker-v3.rst:220: [redirected permanently] http://www.mysql.com/doc/P/a/Pattern_matching.html to https://dev.mysql.com/doc/
user-guide/tracker-v3.rst:251: [redirected permanently] http://www.mysql.com/doc/P/a/Pattern_matching.html to https://dev.mysql.com/doc/
user-guide/wiki.rst:83: [broken] http://yourserver/wiki/index.php?group_id=N&pagename=WiKiPageName: HTTPConnectionPool(host='yourserver', port=80): Max retries exceeded with url: /wiki/index.php?group_id=N&pagename=WiKiPageName (Caused by NewConnectionError('<urllib3.connection.HTTPConnection object at 0x7fa4453c5250>: Failed to establish a new connection: [Errno -2] Name or service not known',))

We should fix those broken links and converts http:// to https://

We should also probably run this linkcheck target on a regular basis.

To modify script_files in the theme is deprecated.

When I run make html, I get this warning:

tuleap-documentation-en/venv/lib/python3.6/site-packages/sphinx_rtd_theme/search.html:21: RemovedInSphinx30Warning: To modify script_files in the theme is deprecated. Please insert a <script> tag directly in your theme instead.

User guide document structure

Hi,

Tuleap's documentation is growing with the tool and as it grows it's getting more difficult to find information regarding any given topic.

The User guide section is where this is most visible, since it currently has 41 topics, but lacks any perceivable structure. The screenshot bellow shows the current state of the User guide menu. Given this scenario, I often find that even alphabetical ordering the menu entries would help to some extent.

My experience with Tuleap, tells me that the desirable structure for me would be to map the platform's own structure, reducing 2nd level topics, grouping them by services when possible, something like:

Project management;
- Dashboard
- Administration;
  - Details;
  - Members;
  - ...;
  - Data;
  - Banner.
Lists management;
...;
Trackers management;
Agile board management.

Important is not rendered properly with docs.tuleap.org theme

See
https://my.enalean.com/doc/en/_sources/user-guide/code-versioning/git.rst.txt

Sphinx default:
https://docs.tuleap.org/user-guide/code-versioning/git.html#fine-grained-permissions

And docs.tuleap.org result:
https://docs.tuleap.org/user-guide/code-versioning/git.html#git-branch-creation-through-tracker-artifact-actions

Add watch target in Makefile

It could be nice if we could have a make watch.

No documentation for the Gantt chart feature

The Gantt chart feature is mentionned a couple of times here and there, but there is no documentation on it. I tried to use it and struggled to get it working with my tracker. I get the sense that it has some expectations as to what fields are present and what type they are, but it isn’t clear what those expectations are. A clear explicit page would be very welcome.

Recommend Projects

React

A declarative, efficient, and flexible JavaScript library for building user interfaces.
Vue.js

🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
Typescript

TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
TensorFlow

An Open Source Machine Learning Framework for Everyone
Django

The Web framework for perfectionists with deadlines.
Laravel

A PHP framework for web artisans
D3

Bring data to life with SVG, Canvas and HTML. 📊📈🎉

Recommend Topics

javascript

JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
web

Some thing interesting about web. New door for the world.
server

A server is a program made to process requests and deliver data to clients.
Machine learning

Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Visualization

Some thing interesting about visualization, use data art
Game

Some thing interesting about game, make everyone happy.

Recommend Org

Facebook

We are working to build community through open source technology. NB: members must have two-factor auth.
Microsoft

Open source projects and samples from Microsoft.
Google

Google ❤️ Open Source for everyone.
Alibaba

Alibaba Open Source for everyone
D3

Data-Driven Documents codes.
Tencent

China tencent open source team.