{"id":20302581,"url":"https://github.com/asterisk/publish-docs","last_synced_at":"2025-03-04T06:42:34.417Z","repository":{"id":11474311,"uuid":"13942714","full_name":"asterisk/publish-docs","owner":"asterisk","description":"The publish-docs utility for Asterisk, takes Asterisk XML documentation and Confluenceizes it","archived":false,"fork":false,"pushed_at":"2023-04-12T10:11:45.000Z","size":51,"stargazers_count":1,"open_issues_count":1,"forks_count":6,"subscribers_count":11,"default_branch":"master","last_synced_at":"2025-01-14T10:59:34.663Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"XSLT","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/asterisk.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2013-10-29T00:42:31.000Z","updated_at":"2023-04-28T18:21:38.000Z","dependencies_parsed_at":"2024-11-15T00:45:48.721Z","dependency_job_id":"84b2b9e3-c03c-4d40-b709-7f7fe4a43f62","html_url":"https://github.com/asterisk/publish-docs","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/asterisk%2Fpublish-docs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/asterisk%2Fpublish-docs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/asterisk%2Fpublish-docs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/asterisk%2Fpublish-docs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/asterisk","download_url":"https://codeload.github.com/asterisk/publish-docs/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":241801194,"owners_count":20022383,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-14T16:32:42.882Z","updated_at":"2025-03-04T06:42:34.400Z","avatar_url":"https://github.com/asterisk.png","language":"XSLT","funding_links":[],"categories":[],"sub_categories":[],"readme":"# publish-docs\n\nThis project contains the scripts used to publish Asterisk's generated\ndocumentation to http://wiki.asterisk.org.\n\nThe top level `publish.sh` should be run from the source directory of\nthe Asterisk version you wish to document. The file\n`~/.asterisk-wiki.conf` should contain the settings for accessing the\n[Confluence wiki server][confluence]. The script has a required\nparameter naming the documentation branch (1.8, 11, 12, etc.).\n\n```bash\n# Example publish-docs configuration file\nCONFLUENCE_URL=https://wiki.asterisk.org/wiki/rpc/xmlrpc\nCONFLUENCE_USER=wikibot\nCONFLUENCE_PASSWORD=peekaboo\n#CONFLUENCE_SPACE=AST\n```\n\nBecause some of the Asterisk documentation can only be generated at\nruntime, the `publish.sh` script will build and install Asterisk to\nthe `/tmp` directory for generating the final documentation.\n\n [confluence]: https://www.atlassian.com/software/confluence\n \n \n## Getting up and running\n\nCheckout Asterisk branch\n\nRun `contrib/scripts/install_prereq` in asterisk checkout directory\n\nYou'll need some dependencies\n\nsudo apt-get install python-dev python-virtualenv python-lxml\n\npip install pystache\n\nYou'll need to run all of this as the root user, its easier to just sudo su!\n\n## Gotchas - until we sort them out in a nice generic way\n\nRunning `publish.sh --dry-run BRANCH_NUMBER` will fail eventually, take the command it outputs and run that directly with `--debug` added to it\n\nSomething like:\n\n```\n/path/to/publish-docs/astxml2wiki.py --username=wikibot --server=https://wiki.asterisk.org/wiki/rpc/xmlrpc '--prefix=Asterisk 12' --space=AST --file=/path/to/publish-docs/asterisk-docs.xml --ast-version=SVN-branch-12-r406327 --diff -v --debug\n```\n\nYou do want to run publish.sh though, as it compiles Asterisk with all the things you need and generates the docs xml file from Asterisk itself\n\nIf you're not changing anything to do with ARI documentation, comment ARI docs generation out of publish.sh - `line 152` in `publish.sh` - it doesn't listen to `--debug` or `--dry-run` properly yet - so it tries to talk to Confluence\n\nThe ARI docs generation DOES NOT handle dry-run or debug, it will try and talk to Confluence and it'll fail if you don't have credentials\n\nIf you are changing `publish-rest-api.py` then you'll likely need to change the interpretter at the top from python2.6\n\npublish.sh looks for a pid file for Asterisk but it fails on my OS, I had to change the path so it worked - `line 202`\n\n```\n-        AST_PID=$(cat ${AST_DIR}/var/run/asterisk/asterisk.pid)\n+        AST_PID=$(cat /var/run/asterisk/asterisk.pid)\n```\n\nI had to increase the sleep commands and add one in publish.sh\n\n```\n         killall -9 asterisk || true # || true so set -e doesn't kill us\n+        sleep 10\n         ${AST_DIR}/sbin/asterisk \u0026\n-        sleep 1\n+        sleep 10\n```\n\nAs sleeping 1 didn't wait long enough to quit Asterisk\n\nHopefully we'll sort these issues out fairly quickly but at least these are documented now\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fasterisk%2Fpublish-docs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fasterisk%2Fpublish-docs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fasterisk%2Fpublish-docs/lists"}